File: snes.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 (3159 lines) | stat: -rw-r--r-- 398,218 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>SNES: Nonlinear 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/snes';</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="TS: Scalable ODE and DAE Solvers" href="ts.html" />
    <link rel="prev" title="KSP: Linear System Solvers" href="ksp.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"><a class="reference internal" href="ksp.html">KSP: Linear System Solvers</a></li>
<li class="toctree-l3 current active"><a class="current reference internal" href="#">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">SNES:...</li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="snes-nonlinear-solvers">
<span id="ch-snes"></span><h1>SNES: Nonlinear Solvers<a class="headerlink" href="#snes-nonlinear-solvers" title="Link to this heading">#</a></h1>
<p>The solution of large-scale nonlinear problems pervades many facets of
computational science and demands robust and flexible solution
strategies. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> library of PETSc provides a powerful suite of
data-structure-neutral numerical routines for such problems. Built on
top of the linear solvers and data structures discussed in preceding
chapters, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> enables the user to easily customize the nonlinear
solvers according to the application at hand. Also, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>
interface is <em>identical</em> for the uniprocess and parallel cases; the only
difference in the parallel version is that each process typically forms
only its local contribution to various matrices and vectors.</p>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> class includes methods for solving systems of nonlinear
equations of the form</p>
<div class="math" id="equation-fx0">
<span class="eqno">(3)<a class="headerlink" href="#equation-fx0" title="Permalink to this equation">#</a></span>\[
\mathbf{F}(\mathbf{x}) = 0,
\]</div>
<p>where <span class="math">\(\mathbf{F}: \, \Re^n \to \Re^n\)</span>. Newton-like methods provide the
core of the package, including both line search and trust region
techniques. A suite of nonlinear Krylov methods and methods based upon
problem decomposition are also included. The solvers are discussed
further in <a class="reference internal" href="#sec-nlsolvers"><span class="std std-ref">The Nonlinear Solvers</span></a>. Following the PETSc design
philosophy, the interfaces to the various solvers are all virtually
identical. In addition, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> software is completely flexible, so
that the user can at runtime change any facet of the solution process.</p>
<p>PETSc’s default method for solving the nonlinear equation is Newton’s
method with line search, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONLS.html">SNESNEWTONLS</a></span></code>. The general form of the <span class="math">\(n\)</span>-dimensional Newton’s method
for solving <a class="reference internal" href="#equation-fx0">(3)</a> is</p>
<div class="math" id="equation-newton">
<span class="eqno">(4)<a class="headerlink" href="#equation-newton" title="Permalink to this equation">#</a></span>\[
\mathbf{x}_{k+1} = \mathbf{x}_k - \mathbf{J}(\mathbf{x}_k)^{-1} \mathbf{F}(\mathbf{x}_k), \;\; k=0,1, \ldots,
\]</div>
<p>where <span class="math">\(\mathbf{x}_0\)</span> is an initial approximation to the solution and
<span class="math">\(\mathbf{J}(\mathbf{x}_k) = \mathbf{F}'(\mathbf{x}_k)\)</span>, the Jacobian, is nonsingular at each
iteration. In practice, the Newton iteration <a class="reference internal" href="#equation-newton">(4)</a> is
implemented by the following two steps:</p>
<div class="math">
\[
\begin{aligned}
1. & \text{(Approximately) solve} & \mathbf{J}(\mathbf{x}_k) \Delta \mathbf{x}_k &= -\mathbf{F}(\mathbf{x}_k). \\
2. & \text{Update} & \mathbf{x}_{k+1} &\gets \mathbf{x}_k + \Delta \mathbf{x}_k.
\end{aligned}
\]</div>
<p>Other defect-correction algorithms can be implemented by using different
choices for <span class="math">\(J(\mathbf{x}_k)\)</span>.</p>
<section id="basic-snes-usage">
<span id="sec-snesusage"></span><h2>Basic SNES Usage<a class="headerlink" href="#basic-snes-usage" title="Link to this heading">#</a></h2>
<p>In the simplest usage of the nonlinear solvers, the user must merely
provide a C, C++, Fortran, or Python routine to evaluate the nonlinear function
<a class="reference internal" href="#equation-fx0">(3)</a>. The corresponding Jacobian matrix
can be approximated with finite differences. For codes that are
typically more efficient and accurate, the user can provide a routine to
compute the Jacobian; details regarding these application-provided
routines are discussed below. To provide an overview of the use of the
nonlinear solvers, browse the concrete example in <a class="reference internal" href="other.html#snes-ex1"><span class="std std-ref">ex1.c</span></a> or skip ahead to the discussion.</p>
<div class="admonition-listing-src-snes-tutorials-ex1-c admonition" id="snes-ex1">
<p class="admonition-title">Listing: <code class="docutils notranslate"><span class="pre">src/snes/tutorials/ex1.c</span></code></p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">help</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Newton&#39;s method for a two-variable system, sequential.</span><span class="se">\n\n</span><span class="s">&quot;</span><span class="p">;</span>

<span class="cm">/*</span>
<span class="cm">   Include &quot;petscsnes.h&quot; so that we can use <a href="../manualpages/SNES/SNES.html">SNES</a> solvers.  Note that this</span>
<span class="cm">   file automatically includes:</span>
<span class="cm">     petscsys.h       - base PETSc routines   petscvec.h - vectors</span>
<span class="cm">     petscmat.h - matrices</span>
<span class="cm">     petscis.h     - index sets            petscksp.h - Krylov subspace methods</span>
<span class="cm">     petscviewer.h - viewers               petscpc.h  - preconditioners</span>
<span class="cm">     petscksp.h   - linear solvers</span>
<span class="cm">*/</span>
<span class="cm">/*F</span>
<span class="cm">This examples solves either</span>
<span class="cm">\begin{equation}</span>
<span class="cm">  F\genfrac{(}{)}{0pt}{}{x_0}{x_1} = \genfrac{(}{)}{0pt}{}{x^2_0 + x_0 x_1 - 3}{x_0 x_1 + x^2_1 - 6}</span>
<span class="cm">\end{equation}</span>
<span class="cm">or if the {\tt -hard} options is given</span>
<span class="cm">\begin{equation}</span>
<span class="cm">  F\genfrac{(}{)}{0pt}{}{x_0}{x_1} = \genfrac{(}{)}{0pt}{}{\sin(3 x_0) + x_0}{x_1}</span>
<span class="cm">\end{equation}</span>
<span class="cm">F*/</span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscsnes.h&gt;</span>

<span class="cm">/*</span>
<span class="cm">   User-defined routines</span>
<span class="cm">*/</span>
<span class="k">extern</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormJacobian1</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</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="k">extern</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormFunction1</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</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="k">extern</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormJacobian2</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</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="k">extern</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormFunction2</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</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="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">**</span><span class="n">argv</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w">        </span><span class="n">snes</span><span class="p">;</span><span class="w"> </span><span class="cm">/* nonlinear solver context */</span>
<span class="w">  </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="cm">/* linear solver context */</span>
<span class="w">  </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="w">   </span><span class="cm">/* preconditioner context */</span>
<span class="w">  </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="w"> </span><span class="n">r</span><span class="p">;</span><span class="w"> </span><span class="cm">/* solution, residual vectors */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w">         </span><span class="n">J</span><span class="p">;</span><span class="w">    </span><span class="cm">/* Jacobian matrix */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscMPIInt.html">PetscMPIInt</a></span><span class="w"> </span><span class="n">size</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">pfive</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">.5</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">;</span>
<span class="w">  </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="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">argv</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">help</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_size.html#MPI_Comm_size">MPI_Comm_size</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">size</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCheck.html">PetscCheck</a></span><span class="p">(</span><span class="n">size</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_ERR_WRONG_MPI_SIZE</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Example is only for sequential runs&quot;</span><span class="p">);</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Create nonlinear solver context</span>
<span class="cm">     - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESCreate.html">SNESCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">snes</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetType.html">SNESSetType</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNESNEWTONLS.html">SNESNEWTONLS</a></span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetOptionsPrefix.html">SNESSetOptionsPrefix</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;mysolver_&quot;</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Create matrix and vector data structures; set corresponding routines</span>
<span class="cm">     - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Create vectors for solution and nonlinear function</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecCreate.html">VecCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecSetSizes.html">VecSetSizes</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecSetFromOptions.html">VecSetFromOptions</a></span><span class="p">(</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">r</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Create Jacobian matrix data structure</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">J</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetSizes.html">MatSetSizes</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetFromOptions.html">MatSetFromOptions</a></span><span class="p">(</span><span class="n">J</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetUp.html">MatSetUp</a></span><span class="p">(</span><span class="n">J</span><span class="p">));</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsHasName.html">PetscOptionsHasName</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-hard&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">flg</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">flg</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="cm">/*</span>
<span class="cm">     Set function evaluation routine and vector.</span>
<span class="cm">    */</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n">FormFunction1</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">    </span><span class="cm">/*</span>
<span class="cm">     Set Jacobian matrix data structure and Jacobian evaluation routine</span>
<span class="cm">    */</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n">FormJacobian1</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n">FormFunction2</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n">FormJacobian2</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Customize nonlinear solver; set runtime options</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set linear solver defaults for this problem. By extracting the</span>
<span class="cm">     <a href="../manualpages/KSP/KSP.html">KSP</a> and <a href="../manualpages/PC/PC.html">PC</a> contexts from the <a href="../manualpages/SNES/SNES.html">SNES</a> context, we can then</span>
<span class="cm">     directly call any <a href="../manualpages/KSP/KSP.html">KSP</a> and <a href="../manualpages/PC/PC.html">PC</a> routines to set various options.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetKSP.html">SNESGetKSP</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</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="w"> </span><span class="o">&amp;</span><span class="n">pc</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></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="w"> </span><span class="n"><a href="../manualpages/PC/PCNONE.html">PCNONE</a></span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSPSetTolerances.html">KSPSetTolerances</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="mf">1.</span><span class="n">e</span><span class="mi">-4</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set <a href="../manualpages/SNES/SNES.html">SNES</a>/<a href="../manualpages/KSP/KSP.html">KSP</a>/<a href="../manualpages/KSP/KSP.html">KSP</a>/<a href="../manualpages/PC/PC.html">PC</a> runtime options, e.g.,</span>
<span class="cm">         -snes_view -snes_monitor -ksp_type &lt;ksp&gt; -pc_type &lt;pc&gt;</span>
<span class="cm">     These options will override those specified above as long as</span>
<span class="cm">     <a href="../manualpages/SNES/SNESSetFromOptions.html">SNESSetFromOptions</a>() is called _after_ any other customization</span>
<span class="cm">     routines.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetFromOptions.html">SNESSetFromOptions</a></span><span class="p">(</span><span class="n">snes</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Evaluate initial guess; then solve nonlinear system</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">flg</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecSet.html">VecSet</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">pfive</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">    </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">2.0</span><span class="p">;</span>
<span class="w">    </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">3.0</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Note: The user should initialize the vector, x, with the initial guess</span>
<span class="cm">     for the nonlinear solver prior to calling <a href="../manualpages/SNES/SNESSolve.html">SNESSolve</a>().  In particular,</span>
<span class="cm">     to employ an initial guess of zero, the user should explicitly set</span>
<span class="cm">     this vector to zero by calling <a href="../manualpages/Vec/VecSet.html">VecSet</a>().</span>
<span class="cm">  */</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSolve.html">SNESSolve</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">flg</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecView.html">VecView</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_WORLD.html">PETSC_VIEWER_STDOUT_WORLD</a></span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetFunction.html">SNESGetFunction</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecView.html">VecView</a></span><span class="p">(</span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_WORLD.html">PETSC_VIEWER_STDOUT_WORLD</a></span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Free work space.  All PETSc objects should be destroyed when they</span>
<span class="cm">     are no longer needed.</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">r</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatDestroy.html">MatDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">J</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESDestroy.html">SNESDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">snes</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a></span><span class="p">());</span>
<span class="w">  </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   FormFunction1 - Evaluates nonlinear function, F(x).</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">.  snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">.  x    - input vector</span>
<span class="cm">.  ctx  - optional user-defined context</span>

<span class="cm">   Output Parameter:</span>
<span class="cm">.  f - function vector</span>
<span class="cm"> */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormFunction1</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</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="p">{</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">       </span><span class="o">*</span><span class="n">ff</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">   Get pointers to vector data.</span>
<span class="cm">      - For default PETSc vectors, <a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a>() returns a pointer to</span>
<span class="cm">        the data array.  Otherwise, the routine is implementation dependent.</span>
<span class="cm">      - You MUST call <a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a>() when you no longer need access to</span>
<span class="cm">        the array.</span>
<span class="cm">   */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArrayRead.html">VecGetArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* Compute function */</span>
<span class="w">  </span><span class="n">ff</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mf">3.0</span><span class="p">;</span>
<span class="w">  </span><span class="n">ff</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mf">6.0</span><span class="p">;</span>

<span class="w">  </span><span class="cm">/* Restore vectors */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArrayRead.html">VecRestoreArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   FormJacobian1 - Evaluates Jacobian matrix.</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">.  snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">.  x - input vector</span>
<span class="cm">.  dummy - optional user-defined context (not used here)</span>

<span class="cm">   Output Parameters:</span>
<span class="cm">.  jac - Jacobian matrix</span>
<span class="cm">.  B - optionally different preconditioning matrix</span>

<span class="cm">*/</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormJacobian1</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">B</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">dummy</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">        </span><span class="n">A</span><span class="p">[</span><span class="mi">4</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">idx</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">};</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get pointer to vector data</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArrayRead.html">VecGetArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Compute Jacobian entries and insert into matrix.</span>
<span class="cm">      - Since this is such a small problem, we set all entries for</span>
<span class="cm">        the matrix at once.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">2.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">2.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">idx</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">idx</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Restore vector</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArrayRead.html">VecRestoreArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Assemble matrix</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a></span><span class="p">(</span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a></span><span class="p">(</span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">jac</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">B</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormFunction2</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</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">dummy</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">       </span><span class="o">*</span><span class="n">ff</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get pointers to vector data.</span>
<span class="cm">       - For default PETSc vectors, <a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a>() returns a pointer to</span>
<span class="cm">         the data array.  Otherwise, the routine is implementation dependent.</span>
<span class="cm">       - You MUST call <a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a>() when you no longer need access to</span>
<span class="cm">         the array.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArrayRead.html">VecGetArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Compute function</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n">ff</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PetscSinScalar</span><span class="p">(</span><span class="mf">3.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="w">  </span><span class="n">ff</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">1</span><span class="p">];</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Restore vectors</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArrayRead.html">VecRestoreArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormJacobian2</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">B</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">dummy</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">        </span><span class="n">A</span><span class="p">[</span><span class="mi">4</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">idx</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">};</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get pointer to vector data</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetArrayRead.html">VecGetArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Compute Jacobian entries and insert into matrix.</span>
<span class="cm">      - Since this is such a small problem, we set all entries for</span>
<span class="cm">        the matrix at once.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">3.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">PetscCosScalar</span><span class="p">(</span><span class="mf">3.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.0</span><span class="p">;</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">0.0</span><span class="p">;</span>
<span class="w">  </span><span class="n">A</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">idx</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">idx</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Restore vector</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArrayRead.html">VecRestoreArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Assemble matrix</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a></span><span class="p">(</span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a></span><span class="p">(</span><span class="n">B</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">jac</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">B</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

</pre></div>
</div>
</div>
<p>To create a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> solver, one must first call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESCreate.html">SNESCreate</a>()</span></code> as
follows:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESCreate.html">SNESCreate</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/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">snes</span><span class="p">);</span>
</pre></div>
</div>
<p>The user must then set routines for evaluating the residual function <a class="reference internal" href="#equation-fx0">(3)</a>
and, <em>possibly</em>, its associated Jacobian matrix, as
discussed in the following sections.</p>
<p>To choose a nonlinear solution method, the user can either call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSetType.html">SNESSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESType.html">SNESType</a></span><span class="w"> </span><span class="n">method</span><span class="p">);</span>
</pre></div>
</div>
<p>or use the option <code class="docutils notranslate"><span class="pre">-snes_type</span> <span class="pre">&lt;method&gt;</span></code>, where details regarding the
available methods are presented in <a class="reference internal" href="#sec-nlsolvers"><span class="std std-ref">The Nonlinear Solvers</span></a>. The
application code can take complete control of the linear and nonlinear
techniques used in the Newton-like method by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSetFromOptions.html">SNESSetFromOptions</a></span><span class="p">(</span><span class="n">snes</span><span class="p">);</span>
</pre></div>
</div>
<p>This routine provides an interface to the PETSc options database, so
that at runtime the user can select a particular nonlinear solver, set
various parameters and customized routines (e.g., specialized line
search variants), prescribe the convergence tolerance, and set
monitoring routines. With this routine the user can also control all
linear solver options in 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> modules, as discussed
in <a class="reference internal" href="ksp.html#ch-ksp"><span class="std std-ref">KSP: Linear System Solvers</span></a>.</p>
<p>After having set these routines and options, the user solves the problem
by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSolve.html">SNESSolve</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">x</span></code> should be initialized to the initial guess before calling and contains the solution on return.
In particular, to employ an initial guess of
zero, the user should explicitly set this vector to zero by calling
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecZeroEntries.html">VecZeroEntries</a>(x)</span></code>. Finally, after solving the nonlinear system (or several
systems), the user should destroy the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> context with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESDestroy.html">SNESDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">snes</span><span class="p">);</span>
</pre></div>
</div>
<section id="nonlinear-function-evaluation">
<span id="sec-snesfunction"></span><h3>Nonlinear Function Evaluation<a class="headerlink" href="#nonlinear-function-evaluation" title="Link to this heading">#</a></h3>
<p>When solving a system of nonlinear equations, the user must provide a
a residual function <a class="reference internal" href="#equation-fx0">(3)</a>, which is set using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</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">FormFunction</span><span class="p">)(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</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>
</pre></div>
</div>
<p>The argument <code class="docutils notranslate"><span class="pre">f</span></code> is an optional vector for storing the solution; pass <code class="docutils notranslate"><span class="pre">NULL</span></code> to have the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> allocate it for you.
The argument <code class="docutils notranslate"><span class="pre">ctx</span></code> is an optional user-defined context, which can
store any private, application-specific data required by the function
evaluation routine; <code class="docutils notranslate"><span class="pre">NULL</span></code> should be used if such information is not
needed. In C and C++, a user-defined context is merely a structure in
which various objects can be stashed; in Fortran a user context can be
an integer array that contains both parameters and pointers to PETSc
objects.
<a href="../src/snes/tutorials/ex5.c.html">SNES Tutorial ex5</a>
and
<a href="../src/snes/tutorials/ex5f90.F90.html">SNES Tutorial ex5f90</a>
give examples of user-defined application contexts in C and Fortran,
respectively.</p>
</section>
<section id="jacobian-evaluation">
<span id="sec-snesjacobian"></span><h3>Jacobian Evaluation<a class="headerlink" href="#jacobian-evaluation" title="Link to this heading">#</a></h3>
<p>The user may also specify a routine to form some approximation of the
Jacobian matrix, <code class="docutils notranslate"><span class="pre">A</span></code>, at the current iterate, <code class="docutils notranslate"><span class="pre">x</span></code>, as is typically
done with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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><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">FormJacobian</span><span class="p">)(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">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">B</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>
</pre></div>
</div>
<p>The arguments of the routine <code class="docutils notranslate"><span class="pre">FormJacobian()</span></code> are the current iterate,
<code class="docutils notranslate"><span class="pre">x</span></code>; the (approximate) Jacobian matrix, <code class="docutils notranslate"><span class="pre">Amat</span></code>; the matrix from
which the preconditioner is constructed, <code class="docutils notranslate"><span class="pre">Pmat</span></code> (which is usually the
same as <code class="docutils notranslate"><span class="pre">Amat</span></code>); and an optional user-defined Jacobian context,
<code class="docutils notranslate"><span class="pre">ctx</span></code>, for application-specific data. The <code class="docutils notranslate"><span class="pre">FormJacobian()</span></code>
callback is only invoked if the solver requires it, always
<em>after</em> <code class="docutils notranslate"><span class="pre">FormFunction()</span></code> has been called at the current iterate.</p>
<p>Note that the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> solvers
are all data-structure neutral, so the full range of PETSc matrix
formats (including “matrix-free” methods) can be used.
<a class="reference internal" href="mat.html#ch-matrices"><span class="std std-ref">Matrices</span></a> discusses information regarding
available matrix formats and options, while <a class="reference internal" href="#sec-nlmatrixfree"><span class="std std-ref">Matrix-Free Methods</span></a> focuses on matrix-free methods in
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>. We briefly touch on a few details of matrix usage that are
particularly important for efficient use of the nonlinear solvers.</p>
<p>A common usage paradigm is to assemble the problem Jacobian in the
preconditioner storage <code class="docutils notranslate"><span class="pre">B</span></code>, rather than <code class="docutils notranslate"><span class="pre">A</span></code>. In the case where they
are identical, as in many simulations, this makes no difference.
However, it allows us to check the analytic Jacobian we construct in
<code class="docutils notranslate"><span class="pre">FormJacobian()</span></code> by passing the <code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code> flag. This
causes PETSc to approximate the Jacobian using finite differencing of
the function evaluation (discussed in <a class="reference internal" href="#sec-fdmatrix"><span class="std std-ref">Finite Difference Jacobian Approximations</span></a>),
and the analytic Jacobian becomes merely the preconditioner. Even if the
analytic Jacobian is incorrect, it is likely that the finite difference
approximation will converge, and thus this is an excellent method to
verify the analytic Jacobian. Moreover, if the analytic Jacobian is
incomplete (some terms are missing or approximate),
<code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code> may be used to obtain the exact solution, where
the Jacobian approximation has been transferred to the preconditioner.</p>
<p>One such approximate Jacobian comes from “Picard linearization”, use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetPicard.html">SNESSetPicard</a>()</span></code>, which
writes the nonlinear system as</p>
<div class="math">
\[
\mathbf{F}(\mathbf{x}) := \mathbf{A}(\mathbf{x}) \mathbf{x} - \mathbf{b} = 0
\]</div>
<p>where <span class="math">\(\mathbf{A}(\mathbf{x})\)</span> usually contains the lower-derivative parts of the
equation. For example, the nonlinear diffusion problem</p>
<div class="math">
\[
- \nabla\cdot(\kappa(u) \nabla u) = 0
\]</div>
<p>would be linearized as</p>
<div class="math">
\[
A(u) v \simeq -\nabla\cdot(\kappa(u) \nabla v).
\]</div>
<p>Usually this linearization is simpler to implement than Newton and the
linear problems are somewhat easier to solve. In addition to using
<code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code> with this approximation to the Jacobian, the
Picard iterative procedure can be performed by defining <span class="math">\(\mathbf{J}(\mathbf{x})\)</span>
to be <span class="math">\(\mathbf{A}(\mathbf{x})\)</span>. Sometimes this iteration exhibits better global
convergence than Newton linearization.</p>
<p>During successive calls to <code class="docutils notranslate"><span class="pre">FormJacobian()</span></code>, the user can either
insert new matrix contexts or reuse old ones, depending on the
application requirements. For many sparse matrix formats, reusing the
old space (and merely changing the matrix elements) is more efficient;
however, if the matrix nonzero structure completely changes, creating an
entirely new matrix context may be preferable. Upon subsequent calls to
the <code class="docutils notranslate"><span class="pre">FormJacobian()</span></code> routine, the user may wish to reinitialize the
matrix entries to zero by calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatZeroEntries.html">MatZeroEntries</a>()</span></code>. See
<a class="reference internal" href="mat.html#sec-othermat"><span class="std std-ref">Other Matrix Operations</span></a> for details on the reuse of the matrix
context.</p>
<p>The directory <code class="docutils notranslate"><span class="pre">$PETSC_DIR/src/snes/tutorials</span></code> provides a variety of
examples.</p>
<p>Sometimes a nonlinear solver may produce a step that is not within the domain
of a given function, for example one with a negative pressure. When this occurs
one can call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunctionDomainError.html">SNESSetFunctionDomainError</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobianDomainError.html">SNESSetJacobianDomainError</a>()</span></code>
to indicate to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> the step is not valid. One must also use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESGetConvergedReason.html">SNESGetConvergedReason</a>()</span></code>
and check the reason to confirm if the solver succeeded. See <a class="reference internal" href="#sec-vi"><span class="std std-ref">Variational Inequalities</span></a> for how to
provide <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> with bounds on the variables to solve (differential) variational inequalities
and how to control properties of the line step computed.</p>
</section>
</section>
<section id="the-nonlinear-solvers">
<span id="sec-nlsolvers"></span><h2>The Nonlinear Solvers<a class="headerlink" href="#the-nonlinear-solvers" title="Link to this heading">#</a></h2>
<p>As summarized in Table <a class="reference internal" href="#tab-snesdefaults"><span class="std std-ref">PETSc Nonlinear Solvers</span></a>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> includes
several Newton-like nonlinear solvers based on line search techniques
and trust region methods. Also provided are several nonlinear Krylov
methods, as well as nonlinear methods involving decompositions of the
problem.</p>
<p>Each solver may have associated with it a set of options, which can be
set with routines and options database commands provided for this
purpose. A complete list can be found by consulting the manual pages or
by running a program with the <code class="docutils notranslate"><span class="pre">-help</span></code> option; we discuss just a few in
the sections below.</p>
<table class="table" id="tab-snesdefaults">
<caption><span class="caption-number">Table 9 </span><span class="caption-text">PETSc Nonlinear Solvers</span><a class="headerlink" href="#tab-snesdefaults" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Method</p></th>
<th class="head"><p>SNESType</p></th>
<th class="head"><p>Options Name</p></th>
<th class="head"><p>Default Line Search</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Line Search Newton</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONLS.html">SNESNEWTONLS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">newtonls</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBT.html">SNESLINESEARCHBT</a></span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Trust region Newton</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONTR.html">SNESNEWTONTR</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">newtontr</span></code></p></td>
<td><p>—</p></td>
</tr>
<tr class="row-even"><td><p>Newton with Arc Length Continuation</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONAL.html">SNESNEWTONAL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">newtonal</span></code></p></td>
<td><p>—</p></td>
</tr>
<tr class="row-odd"><td><p>Nonlinear Richardson</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNRICHARDSON.html">SNESNRICHARDSON</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">nrichardson</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHL2.html">SNESLINESEARCHL2</a></span></code></p></td>
</tr>
<tr class="row-even"><td><p>Nonlinear CG</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNCG.html">SNESNCG</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ncg</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHCP.html">SNESLINESEARCHCP</a></span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Nonlinear GMRES</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNGMRES.html">SNESNGMRES</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ngmres</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHL2.html">SNESLINESEARCHL2</a></span></code></p></td>
</tr>
<tr class="row-even"><td><p>Quasi-Newton</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESQN.html">SNESQN</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">qn</span></code></p></td>
<td><p>see <a class="reference internal" href="#tab-qndefaults"><span class="std std-ref">PETSc quasi-Newton solvers</span></a></p></td>
</tr>
<tr class="row-odd"><td><p>Full Approximation Scheme</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNESFAS/SNESFAS.html">SNESFAS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">fas</span></code></p></td>
<td><p>—</p></td>
</tr>
<tr class="row-even"><td><p>Nonlinear ASM</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNASM.html">SNESNASM</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">nasm</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-odd"><td><p>ASPIN</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESASPIN.html">SNESASPIN</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">aspin</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBT.html">SNESLINESEARCHBT</a></span></code></p></td>
</tr>
<tr class="row-even"><td><p>Nonlinear Gauss-Seidel</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNGS.html">SNESNGS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ngs</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-odd"><td><p>Anderson Mixing</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESANDERSON.html">SNESANDERSON</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">anderson</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-even"><td><p>Newton with constraints (1)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESVINEWTONRSLS.html">SNESVINEWTONRSLS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">vinewtonrsls</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBT.html">SNESLINESEARCHBT</a></span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Newton with constraints (2)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESVINEWTONSSLS.html">SNESVINEWTONSSLS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">vinewtonssls</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBT.html">SNESLINESEARCHBT</a></span></code></p></td>
</tr>
<tr class="row-even"><td><p>Multi-stage Smoothers</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESMS.html">SNESMS</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ms</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-odd"><td><p>Composite</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESCOMPOSITE.html">SNESCOMPOSITE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">composite</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-even"><td><p>Linear solve only</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESKSPONLY.html">SNESKSPONLY</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">ksponly</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-odd"><td><p>Python Shell</p></td>
<td><p><code class="docutils notranslate"><span class="pre">SNESPYTHON</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">python</span></code></p></td>
<td><p>–</p></td>
</tr>
<tr class="row-even"><td><p>Shell (user-defined)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSHELL.html">SNESSHELL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">shell</span></code></p></td>
<td><p>–</p></td>
</tr>
</tbody>
</table>
<section id="line-search-newton">
<h3>Line Search Newton<a class="headerlink" href="#line-search-newton" title="Link to this heading">#</a></h3>
<p>The method <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONLS.html">SNESNEWTONLS</a></span></code> (<code class="docutils notranslate"><span class="pre">-snes_type</span> <span class="pre">newtonls</span></code>) provides a
line search Newton method for solving systems of nonlinear equations. By
default, this technique employs cubic backtracking
<span id="id1">[<a class="reference internal" href="../manualpages/SNES/SNESLINESEARCHBT.html#id2289" title="J. E. Dennis Jr. and Robert B. Schnabel. Numerical Methods for Unconstrained Optimization and Nonlinear Equations. Prentice-Hall, Inc., Englewood Cliffs, NJ, 1983.">DennisJrS83</a>]</span>. Alternative line search techniques are
listed in Table <a class="reference internal" href="#tab-linesearches"><span class="std std-ref">PETSc Line Search Methods</span></a>.</p>
<table class="table" id="tab-linesearches">
<caption><span class="caption-number">Table 10 </span><span class="caption-text">PETSc Line Search Methods</span><a class="headerlink" href="#tab-linesearches" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p><strong>Line Search</strong></p></th>
<th class="head"><p><strong>SNESLineSearchType</strong></p></th>
<th class="head"><p><strong>Options Name</strong></p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Backtracking</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBT.html">SNESLINESEARCHBT</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bt</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>(damped) step</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBASIC.html">SNESLINESEARCHBASIC</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">basic</span></code></p></td>
</tr>
<tr class="row-even"><td><p>identical to above</p></td>
<td><p><code class="docutils notranslate"><span class="pre">SNESLINESEARCHNONE</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>L2-norm Minimization</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHL2.html">SNESLINESEARCHL2</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">l2</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Critical point</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHCP.html">SNESLINESEARCHCP</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">cp</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>Bisection</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBISECTION.html">SNESLINESEARCHBISECTION</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">bisection</span></code></p></td>
</tr>
<tr class="row-even"><td><p>Shell</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHSHELL.html">SNESLINESEARCHSHELL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">shell</span></code></p></td>
</tr>
</tbody>
</table>
<p>Every <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> has a line search context of type <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span></code> that
may be retrieved using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESGetLineSearch.html">SNESGetLineSearch</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="o">*</span><span class="n">ls</span><span class="p">);.</span>
</pre></div>
</div>
<p>There are several default options for the line searches. The order of
polynomial approximation may be set with <code class="docutils notranslate"><span class="pre">-snes_linesearch_order</span></code> or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESLineSearchSetOrder.html">SNESLineSearchSetOrder</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="n">ls</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">order</span><span class="p">);</span>
</pre></div>
</div>
<p>for instance, 2 for quadratic or 3 for cubic. Sometimes, it may not be
necessary to monitor the progress of the nonlinear iteration. In this
case, <code class="docutils notranslate"><span class="pre">-snes_linesearch_norms</span></code> or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESLineSearchSetComputeNorms.html">SNESLineSearchSetComputeNorms</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="n">ls</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">norms</span><span class="p">);</span>
</pre></div>
</div>
<p>may be used to turn off function, step, and solution norm computation at
the end of the linesearch.</p>
<p>The default line search for the line search Newton method,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBT.html">SNESLINESEARCHBT</a></span></code> involves several parameters, which are set to
defaults that are reasonable for many applications. The user can
override the defaults by using the following options:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-snes_linesearch_alpha</span> <span class="pre">&lt;alpha&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_linesearch_maxstep</span> <span class="pre">&lt;max&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_linesearch_minlambda</span> <span class="pre">&lt;tol&gt;</span></code></p></li>
</ul>
<p>Besides the backtracking linesearch, there are <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHL2.html">SNESLINESEARCHL2</a></span></code>,
which uses a polynomial secant minimization of <span class="math">\(||F(x)||_2\)</span>, and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHCP.html">SNESLINESEARCHCP</a></span></code>, which minimizes <span class="math">\(F(x) \cdot Y\)</span> where
<span class="math">\(Y\)</span> is the search direction. These are both potentially iterative
line searches, which may be used to find a better-fitted steplength in
the case where a single secant search is not sufficient. The number of
iterations may be set with <code class="docutils notranslate"><span class="pre">-snes_linesearch_max_it</span></code>. In addition, the
convergence criteria of the iterative line searches may be set using
function tolerances <code class="docutils notranslate"><span class="pre">-snes_linesearch_rtol</span></code> and
<code class="docutils notranslate"><span class="pre">-snes_linesearch_atol</span></code>, and steplength tolerance
<code class="docutils notranslate"><span class="pre">snes_linesearch_ltol</span></code>.</p>
<p>For highly non-linear problems, the bisection line search <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBISECTION.html">SNESLINESEARCHBISECTION</a></span></code>
may prove useful due to its robustness. Similar to the critical point line search
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHCP.html">SNESLINESEARCHCP</a></span></code>, it seeks to find the root of <span class="math">\(F(x) \cdot Y\)</span>.
While the latter does so through a secant method, the bisection line search
does so by iteratively bisecting the step length interval.
It works as follows (with <span class="math">\(f(\lambda)=F(x-\lambda Y) \cdot Y / ||Y||\)</span> for brevity):</p>
<ol class="arabic">
<li><p>initialize: <span class="math">\(j=1\)</span>, <span class="math">\(\lambda_0 = \lambda_{\text{left}} = 0.0\)</span>, <span class="math">\(\lambda_j = \lambda_{\text{right}} = \alpha\)</span>, compute <span class="math">\(f(\lambda_0)\)</span> and <span class="math">\(f(\lambda_j)\)</span></p></li>
<li><p>check whether there is a change of sign in the interval: <span class="math">\(f(\lambda_{\text{left}}) f(\lambda_j) \leq 0\)</span>; if not accept the full step length <span class="math">\(\lambda_1\)</span></p></li>
<li><p>if there is a change of sign, enter iterative bisection procedure</p>
<ol class="arabic simple">
<li><p>check convergence/ exit criteria:</p>
<ul class="simple">
<li><p>absolute tolerance <span class="math">\(f(\lambda_j) &lt; \mathtt{atol}\)</span></p></li>
<li><p>relative tolerance <span class="math">\(f(\lambda_j) &lt; \mathtt{rtol} \cdot f(\lambda_0)\)</span></p></li>
<li><p>change of step length <span class="math">\(\lambda_j - \lambda_{j-1} &lt; \mathtt{ltol}\)</span></p></li>
<li><p>number of iterations <span class="math">\(j &lt; \mathtt{max\_it}\)</span></p></li>
</ul>
</li>
<li><p>if <span class="math">\(j &gt; 1\)</span>, determine direction of bisection</p></li>
</ol>
<div class="math">
\[
   \begin{aligned}\lambda_{\text{left}} &= \begin{cases}\lambda_{\text{left}} &f(\lambda_{\text{left}}) f(\lambda_j) \leq 0\\\lambda_{j} &\text{else}\\ \end{cases}\\ \lambda_{\text{right}} &= \begin{cases} \lambda_j &f(\lambda_{\text{left}}) f(\lambda_j) \leq 0\\\lambda_{\text{right}} &\text{else}\\ \end{cases}\\\end{aligned}
   \]</div>
<ol class="arabic simple" start="3">
<li><p>bisect the interval: <span class="math">\(\lambda_{j+1} = (\lambda_{\text{left}} + \lambda_{\text{right}})/2\)</span>, compute <span class="math">\(f(\lambda_{j+1})\)</span></p></li>
<li><p>update variables for the next iteration: <span class="math">\(\lambda_j \gets \lambda_{j+1}\)</span>, <span class="math">\(f(\lambda_j) \gets f(\lambda_{j+1})\)</span>, <span class="math">\(j \gets j+1\)</span></p></li>
</ol>
</li>
</ol>
<p>Custom line search types may either be defined using
<code class="docutils notranslate"><span class="pre">SNESLineSearchShell</span></code>, or by creating a custom user line search type
in the model of the preexisting ones and register it using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESLineSearchRegister.html">SNESLineSearchRegister</a></span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">sname</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">function</span><span class="p">)(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="p">));.</span>
</pre></div>
</div>
</section>
<section id="trust-region-methods">
<h3>Trust Region Methods<a class="headerlink" href="#trust-region-methods" title="Link to this heading">#</a></h3>
<p>The trust region method in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> for solving systems of nonlinear
equations, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONTR.html">SNESNEWTONTR</a></span></code> (<code class="docutils notranslate"><span class="pre">-snes_type</span> <span class="pre">newtontr</span></code>), is similar to the one developed in the
MINPACK project <span id="id2">[<a class="reference internal" href="#id2283" title="Jorge J. Moré, Danny C. Sorenson, Burton S. Garbow, and Kenneth E. Hillstrom. The MINPACK project. In Wayne R. Cowell, editor, Sources and Development of Mathematical Software, 88–111. 1984.">MoreSGH84</a>]</span>. Several parameters can be
set to control the variation of the trust region size during the
solution process. In particular, the user can control the initial trust
region radius, computed by</p>
<div class="math">
\[
\Delta = \Delta_0 \| F_0 \|_2,
\]</div>
<p>by setting <span class="math">\(\Delta_0\)</span> via the option <code class="docutils notranslate"><span class="pre">-snes_tr_delta0</span> <span class="pre">&lt;delta0&gt;</span></code>.</p>
</section>
<section id="newton-with-arc-length-continuation">
<h3>Newton with Arc Length Continuation<a class="headerlink" href="#newton-with-arc-length-continuation" title="Link to this heading">#</a></h3>
<p>The Newton method with arc length continuation reformulates the linearized system
<span class="math">\(K\delta \mathbf x = -\mathbf F(\mathbf x)\)</span> by introducing the load parameter
<span class="math">\(\lambda\)</span> and splitting the residual into two components, commonly
corresponding to internal and external forces:</p>
<div class="math">
\[
\mathbf F(x, \lambda) = \mathbf F^{\mathrm{int}}(\mathbf x) - \mathbf F^{\mathrm{ext}}(\mathbf x, \lambda)
\]</div>
<p>Often, <span class="math">\(\mathbf F^{\mathrm{ext}}(\mathbf x, \lambda)\)</span> is linear in <span class="math">\(\lambda\)</span>,
which can be thought of as applying the external force in proportional load
increments. By default, this is how the right-hand side vector is handled in the
implemented method. Generally, however, <span class="math">\(\mathbf F^{\mathrm{ext}}(\mathbf x, \lambda)\)</span>
may depend non-linearly on <span class="math">\(\lambda\)</span> or <span class="math">\(\mathbf x\)</span>, or both.
To accommodate this possibility, we provide the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNewtonALGetLoadParameter.html">SNESNewtonALGetLoadParameter</a>()</span></code>
function, which allows for the current value of <span class="math">\(\lambda\)</span> to be queried in the
functions provided to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code>.</p>
<p>Additionally, we split the solution update into two components:</p>
<div class="math">
\[
\delta \mathbf x = \delta s\delta\mathbf x^F + \delta\lambda\delta\mathbf x^Q,
\]</div>
<p>where <span class="math">\(\delta s = 1\)</span> unless partial corrections are used (discussed more
below). Each of <span class="math">\(\delta \mathbf x^F\)</span> and <span class="math">\(\delta \mathbf x^Q\)</span> are found via
solving a linear system with the Jacobian <span class="math">\(K\)</span>:</p>
<ul class="simple">
<li><p><span class="math">\(\delta \mathbf x^F\)</span> is the full Newton step for a given value of <span class="math">\(\lambda\)</span>: <span class="math">\(K \delta \mathbf x^F = -\mathbf F(\mathbf x, \lambda)\)</span></p></li>
<li><p><span class="math">\(\delta \mathbf x^Q\)</span> is the variation in <span class="math">\(\mathbf x\)</span> with respect to <span class="math">\(\lambda\)</span>, computed by <span class="math">\(K \delta\mathbf x^Q = \mathbf Q(\mathbf x, \lambda)\)</span>, where <span class="math">\(\mathbf Q(\mathbf x, \lambda) = -\partial \mathbf F (\mathbf x, \lambda) / \partial \lambda\)</span> is the tangent load vector.</p></li>
</ul>
<p>Often, the tangent load vector <span class="math">\(\mathbf Q\)</span> is constant within a load increment,
which corresponds to the case of proportional loading discussed above. By default,
<span class="math">\(\mathbf Q\)</span> is the full right-hand-side vector, if one was provided.
The user can also provide a function which computes <span class="math">\(\mathbf Q\)</span> to
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNewtonALSetFunction.html">SNESNewtonALSetFunction</a>()</span></code>. This function should have the same signature as for
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a></span></code>, and the user should use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNewtonALGetLoadParameter.html">SNESNewtonALGetLoadParameter</a>()</span></code> to get
<span class="math">\(\lambda\)</span> if it is needed.</p>
<p><strong>The Constraint Surface.</strong> Considering the <span class="math">\(n+1\)</span> dimensional space of
<span class="math">\(\mathbf x\)</span> and <span class="math">\(\lambda\)</span>, we define the linearized equilibrium line to be
the set of points for which the linearized equilibrium equations are satisfied.
Given the previous iterative solution
<span class="math">\(\mathbf t^{(j-1)} = [\mathbf x^{(j-1)}, \lambda^{(j-1)}]\)</span>,
this line is defined by the point <span class="math">\(\mathbf t^{(j-1)} + [\delta\mathbf x^F, 0]\)</span> and
the vector <span class="math">\(\mathbf t^Q [\delta\mathbf x^Q, 1]\)</span>.
The arc length method seeks the intersection of this linearized equilibrium line
with a quadratic constraint surface, defined by</p>
<p>where <span class="math">\(L\)</span> is a user-provided step size corresponding to the radius of the
constraint surface, <span class="math">\(\Delta\mathbf x\)</span> and <span class="math">\(\Delta\lambda\)</span> are the
accumulated updates over the current load step, and <span class="math">\(\psi^2\)</span> is a
user-provided consistency parameter determining the shape of the constraint surface.
Generally, <span class="math">\(\psi^2 &gt; 0\)</span> leads to a hyper-sphere constraint surface, while
<span class="math">\(\psi^2 = 0\)</span> leads to a hyper-cylinder constraint surface.</p>
<p>Since the solution will always fall on the constraint surface, the method will often
require multiple incremental steps to fully solve the non-linear problem.
This is necessary to accurately trace the equilibrium path.
Importantly, this is fundamentally different from time stepping.
While a similar process could be implemented as a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code>, this method is
particularly designed to be used as a SNES, either standalone or within a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code>.</p>
<p>To this end, by default, the load parameter is used such that the full external
forces are applied at <span class="math">\(\lambda = 1\)</span>, although we allow for the user to specify
a different value via <code class="docutils notranslate"><span class="pre">-snes_newtonal_lambda_max</span></code>.
To ensure that the solution corresponds exactly to the external force prescribed by
the user, i.e. that the load parameter is exactly <span class="math">\(\lambda_{max}\)</span> at the end
of the SNES solve, we clamp the value before computing the solution update.
As such, the final increment will likely be a hybrid of arc length continuation and
normal Newton iterations.</p>
<p><strong>Choosing the Continuation Step.</strong> For the first iteration from an equilibrium
point, there is a single correct way to choose <span class="math">\(\delta\lambda\)</span>, which follows
from the constraint equations. Specifically the constraint equations yield the
quadratic equation <span class="math">\(a\delta\lambda^2 + b\delta\lambda + c = 0\)</span>, where</p>
<div class="math">
\[
\begin{aligned}
a &= \|\delta\mathbf x^Q\|^2 + \psi^2,\\
b &= 2\delta\mathbf x^Q\cdot (\Delta\mathbf x + \delta s\delta\mathbf x^F) + 2\psi^2 \Delta\lambda,\\
c &= \|\Delta\mathbf x + \delta s\delta\mathbf x^F\|^2 + \psi^2 \Delta\lambda^2 - L^2.
\end{aligned}
\]</div>
<p>Since in the first iteration, <span class="math">\(\Delta\mathbf x = \delta\mathbf x^F = \mathbf 0\)</span> and
<span class="math">\(\Delta\lambda = 0\)</span>, <span class="math">\(b = 0\)</span> and the equation simplifies to a pair of
real roots:</p>
<div class="math">
\[
\delta\lambda = \pm\frac{L}{\sqrt{\|\delta\mathbf x^Q\|^2 + \psi^2}},
\]</div>
<p>where the sign is positive for the first increment and is determined by the previous
increment otherwise as</p>
<div class="math">
\[
\text{sign}(\delta\lambda) = \text{sign}\big(\delta\mathbf x^Q \cdot (\Delta\mathbf x)_{i-1} + \psi^2(\Delta\lambda)_{i-1}\big),
\]</div>
<p>where <span class="math">\((\Delta\mathbf x)_{i-1}\)</span> and <span class="math">\((\Delta\lambda)_{i-1}\)</span> are the
accumulated updates over the previous load step.</p>
<p>In subsequent iterations, there are different approaches to selecting
<span class="math">\(\delta\lambda\)</span>, all of which have trade-offs.
The main difference is whether the iterative solution falls on the constraint
surface at every iteration, or only when fully converged.
This MR implements one of each of these approaches, set via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNewtonALSetCorrectionType.html">SNESNewtonALSetCorrectionType</a>()</span></code> or
<code class="docutils notranslate"><span class="pre">-snes_newtonal_correction_type</span> <span class="pre">&lt;normal|exact&gt;</span></code> on the command line.</p>
<p><strong>Corrections in the Normal Hyperplane.</strong> The <code class="docutils notranslate"><span class="pre">SNES_NEWTONAL_CORRECTION_NORMAL</span></code>
option is simpler and computationally less expensive, but may fail to converge, as
the constraint equation is not satisfied at every iteration.
The update <span class="math">\(\delta \lambda\)</span> is chosen such that the update is within the
normal hyper-surface to the quadratic constraint surface.
Mathematically, that is</p>
<div class="math">
\[
\delta \lambda = -\frac{\Delta \mathbf x \cdot \delta \mathbf x^F}{\Delta\mathbf x \cdot \delta\mathbf x^Q + \psi^2 \Delta\lambda}.
\]</div>
<p>This implementation is based on <span id="id3">[<a class="reference internal" href="../manualpages/SNES/SNESNEWTONAL.html#id3949" title="Sofie E. Leon, Glaucio H. Paulino, Anderson Pereira, Ivan F. M. Menezes, and Eduardo N. Lages. A unified library of nonlinear solution schemes. Applied Mechanics Reviews, 64(4):040803, July 2011. doi:10.1115/1.4006992.">LPP+11</a>]</span>.</p>
<p><strong>Exact Corrections.</strong> The <code class="docutils notranslate"><span class="pre">SNES_NEWTONAL_CORRECTION_EXACT</span></code> option is far more
complex, but ensures that the constraint is exactly satisfied at every Newton
iteration. As such, it is generally more robust.
By evaluating the intersection of constraint surface and equilibrium line at each
iteration, <span class="math">\(\delta\lambda\)</span> is chosen as one of the roots of the above
quadratic equation <span class="math">\(a\delta\lambda^2 + b\delta\lambda + c = 0\)</span>.
This method encounters issues, however, if the linearized equilibrium line and
constraint surface do not intersect due to particularly large linearized error.
In this case, the roots are complex.
To continue progressing toward a solution, this method uses a partial correction by
choosing <span class="math">\(\delta s\)</span> such that the quadratic equation has a single real root.
Geometrically, this is selecting the point on the constraint surface closest to the
linearized equilibrium line. See the code or <span id="id4">[<a class="reference internal" href="../manualpages/SNES/SNESNEWTONAL.html#id3948" title="Manuel Ritto-Corrêa and Dinar Camotim. On the arc-length and other quadratic control methods: established, less known and new implementation procedures. Computers &amp; Structures, 86(11):1353-1368, June 2008. doi:10.1016/j.compstruc.2007.08.003.">RCorreaC08</a>]</span> for a
mathematical description of these partial corrections.</p>
</section>
<section id="nonlinear-krylov-methods">
<h3>Nonlinear Krylov Methods<a class="headerlink" href="#nonlinear-krylov-methods" title="Link to this heading">#</a></h3>
<p>A number of nonlinear Krylov methods are provided, including Nonlinear
Richardson (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNRICHARDSON.html">SNESNRICHARDSON</a></span></code>), nonlinear conjugate gradient (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNCG.html">SNESNCG</a></span></code>), nonlinear GMRES (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNGMRES.html">SNESNGMRES</a></span></code>), and Anderson Mixing (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESANDERSON.html">SNESANDERSON</a></span></code>). These
methods are described individually below. They are all instrumental to
PETSc’s nonlinear preconditioning.</p>
<p><strong>Nonlinear Richardson.</strong> The nonlinear Richardson iteration, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNRICHARDSON.html">SNESNRICHARDSON</a></span></code>, merely
takes the form of a line search-damped fixed-point iteration of the form</p>
<div class="math">
\[
\mathbf{x}_{k+1} = \mathbf{x}_k - \lambda \mathbf{F}(\mathbf{x}_k), \;\; k=0,1, \ldots,
\]</div>
<p>where the default linesearch is <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHL2.html">SNESLINESEARCHL2</a></span></code>. This simple solver
is mostly useful as a nonlinear smoother, or to provide line search
stabilization to an inner method.</p>
<p><strong>Nonlinear Conjugate Gradients.</strong> Nonlinear CG, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNCG.html">SNESNCG</a></span></code>, is equivalent to linear
CG, but with the steplength determined by line search
(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHCP.html">SNESLINESEARCHCP</a></span></code> by default). Five variants (Fletcher-Reed,
Hestenes-Steifel, Polak-Ribiere-Polyak, Dai-Yuan, and Conjugate Descent)
are implemented in PETSc and may be chosen using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESNCGSetType.html">SNESNCGSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNESNCGType.html">SNESNCGType</a></span><span class="w"> </span><span class="n">btype</span><span class="p">);</span>
</pre></div>
</div>
<p><strong>Anderson Mixing and Nonlinear GMRES Methods.</strong> Nonlinear GMRES (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNGMRES.html">SNESNGMRES</a></span></code>), and
Anderson Mixing (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESANDERSON.html">SNESANDERSON</a></span></code>) methods combine the last <span class="math">\(m\)</span> iterates, plus a new
fixed-point iteration iterate, into an approximate residual-minimizing new iterate.</p>
<p>All of the above methods have support for using a nonlinear preconditioner to compute the preliminary update step, rather than the default
which is the nonlinear function’s residual, $ mathbf{F}(mathbf{x}_k)$. The different update is obtained by solving a nonlinear preconditioner nonlinear problem, which has its own
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> object that may be obtained with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESGetNPC.html">SNESGetNPC</a>()</span></code>.
Quasi-Newton Methods
^^^^^^^^^^^^^^^^^^^^</p>
<p>Quasi-Newton methods store iterative rank-one updates to the Jacobian
instead of computing the Jacobian directly. Three limited-memory quasi-Newton
methods are provided, L-BFGS, which are described in
Table <a class="reference internal" href="#tab-qndefaults"><span class="std std-ref">PETSc quasi-Newton solvers</span></a>. These all are encapsulated under
<code class="docutils notranslate"><span class="pre">-snes_type</span> <span class="pre">qn</span></code> and may be changed with <code class="docutils notranslate"><span class="pre">snes_qn_type</span></code>. The default
is L-BFGS, which provides symmetric updates to an approximate Jacobian.
This iteration is similar to the line search Newton methods.</p>
<p>The quasi-Newton methods support the use of a nonlinear preconditioner that can be obtained with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESGetNPC.html">SNESGetNPC</a>()</span></code> and then configured; or that can be configured with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>, <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 using the options database prefix <code class="docutils notranslate"><span class="pre">-npc_</span></code>.</p>
<table class="table" id="tab-qndefaults">
<caption><span class="caption-number">Table 11 </span><span class="caption-text">PETSc quasi-Newton solvers</span><a class="headerlink" href="#tab-qndefaults" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>QN Method</p></th>
<th class="head"><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESQNType.html">SNESQNType</a></span></code></p></th>
<th class="head"><p>Options Name</p></th>
<th class="head"><p>Default Line Search</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>L-BFGS</p></td>
<td><p><code class="docutils notranslate"><span class="pre">SNES_QN_LBFGS</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lbfgs</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHCP.html">SNESLINESEARCHCP</a></span></code></p></td>
</tr>
<tr class="row-odd"><td><p>“Good” Broyden</p></td>
<td><p><code class="docutils notranslate"><span class="pre">SNES_QN_BROYDEN</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">broyden</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHBASIC.html">SNESLINESEARCHBASIC</a></span></code> (or equivalently <code class="docutils notranslate"><span class="pre">SNESLINESEARCHNONE</span></code></p></td>
</tr>
<tr class="row-even"><td><p>“Bad” Broyden</p></td>
<td><p><code class="docutils notranslate"><span class="pre">SNES_QN_BADBROYDEN</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">badbroyden</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLINESEARCHL2.html">SNESLINESEARCHL2</a></span></code></p></td>
</tr>
</tbody>
</table>
<p>One may also control the form of the initial Jacobian approximation with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESQNSetScaleType.html">SNESQNSetScaleType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNESQNScaleType.html">SNESQNScaleType</a></span><span class="w"> </span><span class="n">stype</span><span class="p">);</span>
</pre></div>
</div>
<p>and the restart type with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESQNSetRestartType.html">SNESQNSetRestartType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNESQNRestartType.html">SNESQNRestartType</a></span><span class="w"> </span><span class="n">rtype</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="the-full-approximation-scheme">
<h3>The Full Approximation Scheme<a class="headerlink" href="#the-full-approximation-scheme" title="Link to this heading">#</a></h3>
<p>The Nonlinear Full Approximation Scheme (FAS) <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNESFAS/SNESFAS.html">SNESFAS</a></span></code>, is a nonlinear multigrid method. At
each level, there is a recursive cycle control <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> instance, and
either one or two nonlinear solvers that act as smoothers (up and down). Problems
set up using the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> interface are automatically
coarsened. FAS, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNESFAS/SNESFAS.html">SNESFAS</a></span></code>, differs slightly from linear multigrid <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code>, in that the hierarchy is
constructed recursively. However, much of the interface is a one-to-one
map. We describe the “get” operations here, and it can be assumed that
each has a corresponding “set” operation. For instance, the number of
levels in the hierarchy may be retrieved using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASGetLevels.html">SNESFASGetLevels</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">levels</span><span class="p">);</span>
</pre></div>
</div>
<p>There are four <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNESFAS/SNESFAS.html">SNESFAS</a></span></code> cycle types, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESFASType.html">SNES_FAS_MULTIPLICATIVE</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESFASType.html">SNES_FAS_ADDITIVE</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESFASType.html">SNES_FAS_FULL</a></span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESFASType.html">SNES_FAS_KASKADE</a></span></code>. The
type may be set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASSetType.html">SNESFASSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESFASType.html">SNESFASType</a></span><span class="w"> </span><span class="n">fastype</span><span class="p">);.</span>
</pre></div>
</div>
<p>and the cycle type, 1 for V, 2 for W, may be set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASSetCycles.html">SNESFASSetCycles</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">cycles</span><span class="p">);.</span>
</pre></div>
</div>
<p>Much like the interface to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code> described in <a class="reference internal" href="ksp.html#sec-mg"><span class="std std-ref">Multigrid Preconditioners</span></a>, there are interfaces to recover the
various levels’ cycles and smoothers. The level smoothers may be
accessed with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASGetSmoother.html">SNESFASGetSmoother</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">level</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">smooth</span><span class="p">);</span>
<span class="n"><a href="../manualpages/SNESFAS/SNESFASGetSmootherUp.html">SNESFASGetSmootherUp</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">level</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">smooth</span><span class="p">);</span>
<span class="n"><a href="../manualpages/SNESFAS/SNESFASGetSmootherDown.html">SNESFASGetSmootherDown</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">level</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">smooth</span><span class="p">);</span>
</pre></div>
</div>
<p>and the level cycles with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASGetCycleSNES.html">SNESFASGetCycleSNES</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">lsnes</span><span class="p">);.</span>
</pre></div>
</div>
<p>Also akin to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code>, the restriction and prolongation at a level may
be acquired with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASGetInterpolation.html">SNESFASGetInterpolation</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">level</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="o">*</span><span class="n">mat</span><span class="p">);</span>
<span class="n"><a href="../manualpages/SNESFAS/SNESFASGetRestriction.html">SNESFASGetRestriction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">level</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="o">*</span><span class="n">mat</span><span class="p">);</span>
</pre></div>
</div>
<p>In addition, FAS requires special restriction for solution-like
variables, called injection. This may be set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASGetInjection.html">SNESFASGetInjection</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">level</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="o">*</span><span class="n">mat</span><span class="p">);.</span>
</pre></div>
</div>
<p>The coarse solve context may be acquired with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNESFAS/SNESFASGetCoarseSolve.html">SNESFASGetCoarseSolve</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">smooth</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="nonlinear-additive-schwarz">
<h3>Nonlinear Additive Schwarz<a class="headerlink" href="#nonlinear-additive-schwarz" title="Link to this heading">#</a></h3>
<p>Nonlinear Additive Schwarz methods (NASM) take a number of local
nonlinear subproblems, solves them independently in parallel, and
combines those solutions into a new approximate solution.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESNASMSetSubdomains.html">SNESNASMSetSubdomains</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">subsnes</span><span class="p">[],</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">iscatter</span><span class="p">[],</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">oscatter</span><span class="p">[],</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">gscatter</span><span class="p">[]);</span>
</pre></div>
</div>
<p>allows for the user to create these local subdomains. Problems set up
using the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> interface are automatically decomposed. To
begin, the type of subdomain updates to the whole solution are limited
to two types borrowed from <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/PCASMType.html">PC_ASM_BASIC</a></span></code>, in which the
overlapping updates added. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCASMType.html">PC_ASM_RESTRICT</a></span></code> updates in a
nonoverlapping fashion. This may be set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESNASMSetType.html">SNESNASMSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESASPIN.html">SNESASPIN</a></span></code> is a helper <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> type that sets up a nonlinearly
preconditioned Newton’s method using NASM as the preconditioner.</p>
</section>
</section>
<section id="general-options">
<h2>General Options<a class="headerlink" href="#general-options" title="Link to this heading">#</a></h2>
<p>This section discusses options and routines that apply to all <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>
solvers and problem classes. In particular, we focus on convergence
tests, monitoring routines, and tools for checking derivative
computations.</p>
<section id="convergence-tests">
<span id="sec-snesconvergence"></span><h3>Convergence Tests<a class="headerlink" href="#convergence-tests" title="Link to this heading">#</a></h3>
<p>Convergence of the nonlinear solvers can be detected in a variety of
ways; the user can even specify a customized test, as discussed below.
Most of the nonlinear solvers use <code class="docutils notranslate"><span class="pre">SNESConvergenceTestDefault()</span></code>,
however, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESNEWTONTR.html">SNESNEWTONTR</a></span></code> uses a method-specific additional convergence
test as well. The convergence tests involves several parameters, which
are set by default to values that should be reasonable for a wide range
of problems. The user can customize the parameters to the problem at
hand by using some of the following routines and options.</p>
<p>One method of convergence testing is to declare convergence when the
norm of the change in the solution between successive iterations is less
than some tolerance, <code class="docutils notranslate"><span class="pre">stol</span></code>. Convergence can also be determined based
on the norm of the function. Such a test can use either the absolute
size of the norm, <code class="docutils notranslate"><span class="pre">atol</span></code>, or its relative decrease, <code class="docutils notranslate"><span class="pre">rtol</span></code>, from an
initial guess. The following routine sets these parameters, which are
used in many of the default <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> convergence tests:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSetTolerances.html">SNESSetTolerances</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">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">stol</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">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">fcts</span><span class="p">);</span>
</pre></div>
</div>
<p>This routine also sets the maximum numbers of allowable nonlinear
iterations, <code class="docutils notranslate"><span class="pre">its</span></code>, and function evaluations, <code class="docutils notranslate"><span class="pre">fcts</span></code>. The
corresponding options database commands for setting these parameters are:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-snes_atol</span> <span class="pre">&lt;atol&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_rtol</span> <span class="pre">&lt;rtol&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_stol</span> <span class="pre">&lt;stol&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_max_it</span> <span class="pre">&lt;its&gt;</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_max_funcs</span> <span class="pre">&lt;fcts&gt;</span></code> (use <code class="docutils notranslate"><span class="pre">unlimited</span></code> for no maximum)</p></li>
</ul>
<p>A related routine is <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESGetTolerances.html">SNESGetTolerances</a>()</span></code>. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span></code> may be used
for any parameter to indicate the current value should be retained; use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_DETERMINE.html">PETSC_DETERMINE</a></span></code> to restore to the default value from when the object was created.</p>
<p>Users can set their own customized convergence tests in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> by
using the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESSetConvergenceTest.html">SNESSetConvergenceTest</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">xnorm</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">gnorm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">f</span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESConvergedReason.html">SNESConvergedReason</a></span><span class="w"> </span><span class="n">reason</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">cctx</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">cctx</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">cctx</span><span class="p">));</span>
</pre></div>
</div>
<p>The final argument of the convergence test routine, <code class="docutils notranslate"><span class="pre">cctx</span></code>, denotes an
optional user-defined context for private data. When solving systems of
nonlinear equations, the arguments <code class="docutils notranslate"><span class="pre">xnorm</span></code>, <code class="docutils notranslate"><span class="pre">gnorm</span></code>, and <code class="docutils notranslate"><span class="pre">f</span></code> are
the current iterate norm, current step norm, and function norm,
respectively. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESConvergedReason.html">SNESConvergedReason</a></span></code> should be set positive for
convergence and negative for divergence. See <code class="docutils notranslate"><span class="pre">include/petscsnes.h</span></code> for
a list of values for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESConvergedReason.html">SNESConvergedReason</a></span></code>.</p>
</section>
<section id="convergence-monitoring">
<span id="sec-snesmonitor"></span><h3>Convergence Monitoring<a class="headerlink" href="#convergence-monitoring" title="Link to this heading">#</a></h3>
<p>By default the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> solvers run silently without displaying
information about the iterations. The user can initiate monitoring with
the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESMonitorSet.html">SNESMonitorSet</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">its</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">norm</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">mctx</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">mctx</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="o">*</span><span class="n">monitordestroy</span><span class="p">);</span>
</pre></div>
</div>
<p>The routine, <code class="docutils notranslate"><span class="pre">mon</span></code>, indicates a user-defined monitoring routine, where
<code class="docutils notranslate"><span class="pre">its</span></code> and <code class="docutils notranslate"><span class="pre">mctx</span></code> respectively denote the iteration number and an
optional user-defined context for private data for the monitor routine.
The argument <code class="docutils notranslate"><span class="pre">norm</span></code> is the function norm.</p>
<p>The routine set by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESMonitorSet.html">SNESMonitorSet</a>()</span></code> is called once after every
successful step computation within the nonlinear solver. Hence, the user
can employ this routine for any application-specific computations that
should be done after the solution update. The option <code class="docutils notranslate"><span class="pre">-snes_monitor</span></code>
activates the default <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> monitor routine,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESMonitorDefault.html">SNESMonitorDefault</a>()</span></code>, while <code class="docutils notranslate"><span class="pre">-snes_monitor_lg_residualnorm</span></code> draws
a simple line graph of the residual norm’s convergence.</p>
<p>One can cancel hardwired monitoring routines for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> at runtime
with <code class="docutils notranslate"><span class="pre">-snes_monitor_cancel</span></code>.</p>
<p>As the Newton method converges so that the residual norm is small, say
<span class="math">\(10^{-10}\)</span>, many of the final digits printed with the
<code class="docutils notranslate"><span class="pre">-snes_monitor</span></code> option are meaningless. Worse, they are different on
different machines; due to different round-off rules used by, say, the
IBM RS6000 and the Sun SPARC. This makes testing between different
machines difficult. The option <code class="docutils notranslate"><span class="pre">-snes_monitor_short</span></code> causes PETSc to
print fewer of the digits of the residual norm as it gets smaller; thus
on most of the machines it will always print the same numbers making
cross-process testing easier.</p>
<p>The routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESGetSolution.html">SNESGetSolution</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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/SNES/SNESGetFunction.html">SNESGetFunction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">r</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">int</span><span class="p">(</span><span class="o">**</span><span class="n">func</span><span class="p">)(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</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="kt">void</span><span class="o">*</span><span class="p">));</span>
</pre></div>
</div>
<p>return the solution vector and function vector from a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> context.
These routines are useful, for instance, if the convergence test
requires some property of the solution or function other than those
passed with routine arguments.</p>
</section>
<section id="checking-accuracy-of-derivatives">
<span id="sec-snesderivs"></span><h3>Checking Accuracy of Derivatives<a class="headerlink" href="#checking-accuracy-of-derivatives" title="Link to this heading">#</a></h3>
<p>Since hand-coding routines for Jacobian matrix evaluation can be error
prone, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> provides easy-to-use support for checking these matrices
against finite difference versions. In the simplest form of comparison,
users can employ the option <code class="docutils notranslate"><span class="pre">-snes_test_jacobian</span></code> to compare the
matrices at several points. Although not exhaustive, this test will
generally catch obvious problems. One can compare the elements of the
two matrices by using the option <code class="docutils notranslate"><span class="pre">-snes_test_jacobian_view</span></code> , which
causes the two matrices to be printed to the screen.</p>
<p>Another means for verifying the correctness of a code for Jacobian
computation is running the problem with either the finite difference or
matrix-free variant, <code class="docutils notranslate"><span class="pre">-snes_fd</span></code> or <code class="docutils notranslate"><span class="pre">-snes_mf</span></code>; see <a class="reference internal" href="#sec-fdmatrix"><span class="std std-ref">Finite Difference Jacobian Approximations</span></a> or <a class="reference internal" href="#sec-nlmatrixfree"><span class="std std-ref">Matrix-Free Methods</span></a>.
If a
problem converges well with these matrix approximations but not with a
user-provided routine, the problem probably lies with the hand-coded
matrix. See the note in <a class="reference internal" href="#sec-snesjacobian"><span class="std std-ref">Jacobian Evaluation</span></a> about
assembling your Jabobian in the “preconditioner” slot <code class="docutils notranslate"><span class="pre">Pmat</span></code>.</p>
<p>The correctness of user provided <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSHELL.html">MATSHELL</a></span></code> Jacobians in general can be
checked with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatShellTestMultTranspose.html">MatShellTestMultTranspose</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatShellTestMult.html">MatShellTestMult</a>()</span></code>.</p>
<p>The correctness of user provided <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSHELL.html">MATSHELL</a></span></code> Jacobians via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a>()</span></code>
can be checked with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRHSJacobianTestTranspose.html">TSRHSJacobianTestTranspose</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRHSJacobianTest.html">TSRHSJacobianTest</a>()</span></code>
that check the correction of the matrix-transpose vector product and the
matrix-product. From the command line, these can be checked with</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-ts_rhs_jacobian_test_mult_transpose</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mat_shell_test_mult_transpose_view</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_rhs_jacobian_test_mult</span></code></p></li>
<li><p><code class="docutils notranslate"><span class="pre">-mat_shell_test_mult_view</span></code></p></li>
</ul>
</section>
</section>
<section id="inexact-newton-like-methods">
<h2>Inexact Newton-like Methods<a class="headerlink" href="#inexact-newton-like-methods" title="Link to this heading">#</a></h2>
<p>Since exact solution of the linear Newton systems within <a class="reference internal" href="#equation-newton">(4)</a>
at each iteration can be costly, modifications
are often introduced that significantly reduce these expenses and yet
retain the rapid convergence of Newton’s method. Inexact or truncated
Newton techniques approximately solve the linear systems using an
iterative scheme. In comparison with using direct methods for solving
the Newton systems, iterative methods have the virtue of requiring
little space for matrix storage and potentially saving significant
computational work. Within the class of inexact Newton methods, of
particular interest are Newton-Krylov methods, where the subsidiary
iterative technique for solving the Newton system is chosen from the
class of Krylov subspace projection methods. Note that at runtime the
user can set any of the linear solver options discussed in <a class="reference internal" href="ksp.html#ch-ksp"><span class="std std-ref">KSP: Linear System Solvers</span></a>,
such as <code class="docutils notranslate"><span class="pre">-ksp_type</span> <span class="pre">&lt;ksp_method&gt;</span></code> and
<code class="docutils notranslate"><span class="pre">-pc_type</span> <span class="pre">&lt;pc_method&gt;</span></code>, to set the Krylov subspace and preconditioner
methods.</p>
<p>Two levels of iterations occur for the inexact techniques, where during
each global or outer Newton iteration a sequence of subsidiary inner
iterations of a linear solver is performed. Appropriate control of the
accuracy to which the subsidiary iterative method solves the Newton
system at each global iteration is critical, since these inner
iterations determine the asymptotic convergence rate for inexact Newton
techniques. While the Newton systems must be solved well enough to
retain fast local convergence of the Newton’s iterates, use of excessive
inner iterations, particularly when <span class="math">\(\| \mathbf{x}_k - \mathbf{x}_* \|\)</span> is large,
is neither necessary nor economical. Thus, the number of required inner
iterations typically increases as the Newton process progresses, so that
the truncated iterates approach the true Newton iterates.</p>
<p>A sequence of nonnegative numbers <span class="math">\(\{\eta_k\}\)</span> can be used to
indicate the variable convergence criterion. In this case, when solving
a system of nonlinear equations, the update step of the Newton process
remains unchanged, and direct solution of the linear system is replaced
by iteration on the system until the residuals</p>
<div class="math">
\[
\mathbf{r}_k^{(i)} =  \mathbf{F}'(\mathbf{x}_k) \Delta \mathbf{x}_k + \mathbf{F}(\mathbf{x}_k)
\]</div>
<p>satisfy</p>
<div class="math">
\[
\frac{ \| \mathbf{r}_k^{(i)} \| }{ \| \mathbf{F}(\mathbf{x}_k) \| } \leq \eta_k \leq \eta < 1.
\]</div>
<p>Here <span class="math">\(\mathbf{x}_0\)</span> is an initial approximation of the solution, and
<span class="math">\(\| \cdot \|\)</span> denotes an arbitrary norm in <span class="math">\(\Re^n\)</span> .</p>
<p>By default a constant relative convergence tolerance is used for solving
the subsidiary linear systems within the Newton-like methods of
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>. When solving a system of nonlinear equations, one can instead
employ the techniques of Eisenstat and Walker <span id="id5">[<a class="reference internal" href="../manualpages/Tao/TaoKSPSetUseEW.html#id1300" title="S. C. Eisenstat and H. F. Walker. Choosing the forcing terms in an inexact Newton method. SIAM J. Scientific Computing, 17:16–32, 1996.">EW96</a>]</span>
to compute <span class="math">\(\eta_k\)</span> at each step of the nonlinear solver by using
the option <code class="docutils notranslate"><span class="pre">-snes_ksp_ew</span></code> . In addition, by adding one’s own
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> convergence test (see <a class="reference internal" href="ksp.html#sec-convergencetests"><span class="std std-ref">Convergence Tests</span></a>), one can easily create one’s own,
problem-dependent, inner convergence tests.</p>
</section>
<section id="matrix-free-methods">
<span id="sec-nlmatrixfree"></span><h2>Matrix-Free Methods<a class="headerlink" href="#matrix-free-methods" title="Link to this heading">#</a></h2>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> class fully supports matrix-free methods. The matrices
specified in the Jacobian evaluation routine need not be conventional
matrices; instead, they can point to the data required to implement a
particular matrix-free method. The matrix-free variant is allowed <em>only</em>
when the linear systems are solved by an iterative method in combination
with no preconditioning (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCNONE.html">PCNONE</a></span></code> or <code class="docutils notranslate"><span class="pre">-pc_type</span></code> <code class="docutils notranslate"><span class="pre">none</span></code>), a
user-provided preconditioner matrix, or a user-provided preconditioner
shell (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSHELL.html">PCSHELL</a></span></code>, discussed in <a class="reference internal" href="ksp.html#sec-pc"><span class="std std-ref">Preconditioners</span></a>); that
is, obviously matrix-free methods cannot be used with a direct solver,
approximate factorization, or other preconditioner which requires access
to explicit matrix entries.</p>
<p>The user can create a matrix-free context for use within <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> with
the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/MatCreateSNESMF.html">MatCreateSNESMF</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="o">*</span><span class="n">mat</span><span class="p">);</span>
</pre></div>
</div>
<p>This routine creates the data structures needed for the matrix-vector
products that arise within Krylov space iterative
methods <span id="id6">[<a class="reference internal" href="#id1268" title="Peter N. Brown and Youcef Saad. Hybrid Krylov methods for nonlinear systems of equations. SIAM J. Sci. Stat. Comput., 11:450-481, 1990.">BS90</a>]</span>.
The default <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>
matrix-free approximations can also be invoked with the command
<code class="docutils notranslate"><span class="pre">-snes_mf</span></code>. Or, one can retain the user-provided Jacobian
preconditioner, but replace the user-provided Jacobian matrix with the
default matrix-free variant with the option <code class="docutils notranslate"><span class="pre">-snes_mf_operator</span></code>.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/MatCreateSNESMF.html">MatCreateSNESMF</a>()</span></code> uses</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatCreateMFFD.html">MatCreateMFFD</a></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="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="o">*</span><span class="n">mat</span><span class="p">);</span>
</pre></div>
</div>
<p>which can also be used directly for users who need a matrix-free matrix but are not using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>.</p>
<p>The user can set one parameter to control the Jacobian-vector product
approximation with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatMFFDSetFunctionError.html">MatMFFDSetFunctionError</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><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">rerror</span><span class="p">);</span>
</pre></div>
</div>
<p>The parameter <code class="docutils notranslate"><span class="pre">rerror</span></code> should be set to the square root of the
relative error in the function evaluations, <span class="math">\(e_{rel}\)</span>; the default
is the square root of machine epsilon (about <span class="math">\(10^{-8}\)</span> in double
precision), which assumes that the functions are evaluated to full
floating-point precision accuracy. This parameter can also be set from
the options database with <code class="docutils notranslate"><span class="pre">-mat_mffd_err</span> <span class="pre">&lt;err&gt;</span></code></p>
<p>In addition, PETSc provides ways to register new routines to compute
the differencing parameter (<span class="math">\(h\)</span>); see the manual page for
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMFFDSetType.html">MatMFFDSetType</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMFFDRegister.html">MatMFFDRegister</a>()</span></code>. We currently provide two
default routines accessible via <code class="docutils notranslate"><span class="pre">-mat_mffd_type</span> <span class="pre">&lt;ds</span> <span class="pre">or</span> <span class="pre">wp&gt;</span></code>. For
the default approach there is one “tuning” parameter, set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatMFFDDSSetUmin.html">MatMFFDDSSetUmin</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><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">umin</span><span class="p">);</span>
</pre></div>
</div>
<p>This parameter, <code class="docutils notranslate"><span class="pre">umin</span></code> (or <span class="math">\(u_{min}\)</span>), is a bit involved; its
default is <span class="math">\(10^{-6}\)</span> . Its command line form is <code class="docutils notranslate"><span class="pre">-mat_mffd_umin</span> <span class="pre">&lt;umin&gt;</span></code>.</p>
<p>The Jacobian-vector product is approximated
via the formula</p>
<div class="math">
\[
F'(u) a \approx \frac{F(u + h*a) - F(u)}{h}
\]</div>
<p>where <span class="math">\(h\)</span> is computed via</p>
<div class="math">
\[
h = e_{\text{rel}} \cdot \begin{cases}
u^{T}a/\lVert a \rVert^2_2                                 & \text{if $|u^T a| > u_{\min} \lVert a \rVert_{1}$} \\
u_{\min} \operatorname{sign}(u^{T}a) \lVert a \rVert_{1}/\lVert a\rVert^2_2  & \text{otherwise}.
\end{cases}
\]</div>
<p>This approach is taken from Brown and Saad
<span id="id7">[<a class="reference internal" href="#id1268" title="Peter N. Brown and Youcef Saad. Hybrid Krylov methods for nonlinear systems of equations. SIAM J. Sci. Stat. Comput., 11:450-481, 1990.">BS90</a>]</span>. The second approach, taken from Walker and Pernice,
<span id="id8">[<a class="reference internal" href="../manualpages/Mat/MatMFFDWPSetComputeNormU.html#id1220" title="M. Pernice and H. F. Walker. NITSOL: a Newton iterative solver for nonlinear systems. SIAM J. Sci. Stat. Comput., 19:302–318, 1998.">PW98</a>]</span>, computes <span class="math">\(h\)</span> via</p>
<div class="math">
\[
\begin{aligned}
        h = \frac{\sqrt{1 + ||u||}e_{rel}}{||a||}\end{aligned}
\]</div>
<p>This has no tunable parameters, but note that inside the nonlinear solve
for the entire <em>linear</em> iterative process <span class="math">\(u\)</span> does not change
hence <span class="math">\(\sqrt{1 + ||u||}\)</span> need be computed only once. This
information may be set with the options</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatMFFDWPSetComputeNormU.html">MatMFFDWPSetComputeNormU</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><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="p">);</span>
</pre></div>
</div>
<p>or <code class="docutils notranslate"><span class="pre">-mat_mffd_compute_normu</span> <span class="pre">&lt;true</span> <span class="pre">or</span> <span class="pre">false&gt;</span></code>. This information is used
to eliminate the redundant computation of these parameters, therefore
reducing the number of collective operations and improving the
efficiency of the application code. This takes place automatically for the PETSc GMRES solver with left preconditioning.</p>
<p>It is also possible to monitor the differencing parameters h that are
computed via the routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatMFFDSetHHistory.html">MatMFFDSetHHistory</a></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/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="p">,</span><span class="kt">int</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Mat/MatMFFDResetHHistory.html">MatMFFDResetHHistory</a></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/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="p">,</span><span class="kt">int</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Mat/MatMFFDGetH.html">MatMFFDGetH</a></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/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<p>We include an explicit example of using matrix-free methods in <a class="reference internal" href="#snes-ex3"><span class="std std-ref">ex3.c</span></a>.
Note that by using the option <code class="docutils notranslate"><span class="pre">-snes_mf</span></code> one can
easily convert any <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> code to use a matrix-free Newton-Krylov
method without a preconditioner. As shown in this example,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetFromOptions.html">SNESSetFromOptions</a>()</span></code> must be called <em>after</em> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code> to
enable runtime switching between the user-specified Jacobian and the
default <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> matrix-free form.</p>
<div class="admonition-listing-src-snes-tutorials-ex3-c admonition" id="snes-ex3">
<p class="admonition-title">Listing: <code class="docutils notranslate"><span class="pre">src/snes/tutorials/ex3.c</span></code></p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">help</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Newton methods to solve u&#39;&#39; + u^{2} = f in parallel.</span><span class="se">\n</span><span class="s">\</span>
<span class="s">This example employs a user-defined monitoring routine and optionally a user-defined</span><span class="se">\n</span><span class="s">\</span>
<span class="s">routine to check candidate iterates produced by line search routines.</span><span class="se">\n</span><span class="s">\</span>
<span class="s">The command line options include:</span><span class="se">\n</span><span class="s">\</span>
<span class="s">  -pre_check_iterates : activate checking of iterates</span><span class="se">\n</span><span class="s">\</span>
<span class="s">  -post_check_iterates : activate checking of iterates</span><span class="se">\n</span><span class="s">\</span>
<span class="s">  -check_tol &lt;tol&gt;: set tolerance for iterate checking</span><span class="se">\n</span><span class="s">\</span>
<span class="s">  -user_precond : activate a (trivial) user-defined preconditioner</span><span class="se">\n\n</span><span class="s">&quot;</span><span class="p">;</span>

<span class="cm">/*</span>
<span class="cm">   Include &quot;petscdm.h&quot; so that we can use data management objects (DMs)</span>
<span class="cm">   Include &quot;petscdmda.h&quot; so that we can use distributed arrays (DMDAs).</span>
<span class="cm">   Include &quot;petscsnes.h&quot; so that we can use <a href="../manualpages/SNES/SNES.html">SNES</a> solvers.  Note that this</span>
<span class="cm">   file automatically includes:</span>
<span class="cm">     petscsys.h    - base PETSc routines</span>
<span class="cm">     petscvec.h    - vectors</span>
<span class="cm">     petscmat.h    - matrices</span>
<span class="cm">     petscis.h     - index sets</span>
<span class="cm">     petscksp.h    - Krylov subspace methods</span>
<span class="cm">     petscviewer.h - viewers</span>
<span class="cm">     petscpc.h     - preconditioners</span>
<span class="cm">     petscksp.h    - linear solvers</span>
<span class="cm">*/</span>

<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscdm.h&gt;</span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscdmda.h&gt;</span>
<span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscsnes.h&gt;</span>

<span class="cm">/*</span>
<span class="cm">   User-defined routines.</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormJacobian</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormFunction</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormInitialGuess</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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">Monitor</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="w"> </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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PreCheck</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PostCheck</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PostSetSubKSP</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</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/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">MatrixFreePreconditioner</span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">);</span>

<span class="cm">/*</span>
<span class="cm">   User-defined application context</span>
<span class="cm">*/</span>
<span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w">          </span><span class="n">da</span><span class="p">;</span><span class="w">    </span><span class="cm">/* distributed array */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">         </span><span class="n">F</span><span class="p">;</span><span class="w">     </span><span class="cm">/* right-hand side of PDE */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscMPIInt.html">PetscMPIInt</a></span><span class="w"> </span><span class="n">rank</span><span class="p">;</span><span class="w">  </span><span class="cm">/* rank of processor */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscMPIInt.html">PetscMPIInt</a></span><span class="w"> </span><span class="n">size</span><span class="p">;</span><span class="w">  </span><span class="cm">/* size of communicator */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w">   </span><span class="n">h</span><span class="p">;</span><span class="w">     </span><span class="cm">/* mesh spacing */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w">   </span><span class="n">sjerr</span><span class="p">;</span><span class="w"> </span><span class="cm">/* if or not to test jacobian domain error */</span>
<span class="p">}</span><span class="w"> </span><span class="n">ApplicationCtx</span><span class="p">;</span>

<span class="cm">/*</span>
<span class="cm">   User-defined context for monitoring</span>
<span class="cm">*/</span>
<span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span><span class="w"> </span><span class="n">viewer</span><span class="p">;</span>
<span class="p">}</span><span class="w"> </span><span class="n">MonitorCtx</span><span class="p">;</span>

<span class="cm">/*</span>
<span class="cm">   User-defined context for checking candidate iterates that are</span>
<span class="cm">   determined by line search methods</span>
<span class="cm">*/</span>
<span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">             </span><span class="n">last_step</span><span class="p">;</span><span class="w"> </span><span class="cm">/* previous iterate */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w">       </span><span class="n">tolerance</span><span class="p">;</span><span class="w"> </span><span class="cm">/* tolerance for changes between successive iterates */</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="n">user</span><span class="p">;</span>
<span class="p">}</span><span class="w"> </span><span class="n">StepCheckCtx</span><span class="p">;</span>

<span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </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">its0</span><span class="p">;</span><span class="w"> </span><span class="cm">/* num of previous outer <a href="../manualpages/KSP/KSP.html">KSP</a> iterations */</span>
<span class="p">}</span><span class="w"> </span><span class="n">SetSubKSPCtx</span><span class="p">;</span>

<span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">**</span><span class="n">argv</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w">           </span><span class="n">snes</span><span class="p">;</span><span class="w">       </span><span class="cm">/* <a href="../manualpages/SNES/SNES.html">SNES</a> context */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="n">linesearch</span><span class="p">;</span><span class="w"> </span><span class="cm">/* <a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a> context */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w">            </span><span class="n">J</span><span class="p">;</span><span class="w">          </span><span class="cm">/* Jacobian matrix */</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="n">ctx</span><span class="p">;</span><span class="w">        </span><span class="cm">/* user-defined context */</span>
<span class="w">  </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="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n">U</span><span class="p">,</span><span class="w"> </span><span class="n">F</span><span class="p">;</span><span class="w"> </span><span class="cm">/* vectors */</span>
<span class="w">  </span><span class="n">MonitorCtx</span><span class="w">     </span><span class="n">monP</span><span class="p">;</span><span class="w">       </span><span class="cm">/* monitoring context */</span>
<span class="w">  </span><span class="n">StepCheckCtx</span><span class="w">   </span><span class="n">checkP</span><span class="p">;</span><span class="w">     </span><span class="cm">/* step-checking context */</span>
<span class="w">  </span><span class="n">SetSubKSPCtx</span><span class="w">   </span><span class="n">checkP1</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w">      </span><span class="n">pre_check</span><span class="p">,</span><span class="w"> </span><span class="n">post_check</span><span class="p">,</span><span class="w"> </span><span class="n">post_setsubksp</span><span class="p">;</span><span class="w"> </span><span class="cm">/* flag indicating whether we&#39;re checking candidate iterates */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">    </span><span class="n">xp</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">FF</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">UU</span><span class="p">,</span><span class="w"> </span><span class="n">none</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">-1.0</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">its</span><span class="p">,</span><span class="w"> </span><span class="n">N</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="n">maxit</span><span class="p">,</span><span class="w"> </span><span class="n">maxf</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">xm</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">abstol</span><span class="p">,</span><span class="w"> </span><span class="n">rtol</span><span class="p">,</span><span class="w"> </span><span class="n">stol</span><span class="p">,</span><span class="w"> </span><span class="n">norm</span><span class="p">;</span>
<span class="w">  </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="w"> </span><span class="n">viewinitial</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">argv</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">help</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_rank.html#MPI_Comm_rank">MPI_Comm_rank</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">.</span><span class="n">rank</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCallMPI.html">PetscCallMPI</a></span><span class="p">(</span><span class="n"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Comm_size.html#MPI_Comm_size">MPI_Comm_size</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">.</span><span class="n">size</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsGetInt.html">PetscOptionsGetInt</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-n&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">N</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="n">ctx</span><span class="p">.</span><span class="n">h</span><span class="w">     </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">(</span><span class="n">N</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
<span class="w">  </span><span class="n">ctx</span><span class="p">.</span><span class="n">sjerr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsGetBool.html">PetscOptionsGetBool</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-test_jacobian_domain_error&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">.</span><span class="n">sjerr</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsGetBool.html">PetscOptionsGetBool</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-view_initial&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">viewinitial</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Create nonlinear solver context</span>
<span class="cm">     - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESCreate.html">SNESCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">snes</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Create vector data structures; set function evaluation routine</span>
<span class="cm">     - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Create distributed array (<a href="../manualpages/DMDA/DMDA.html">DMDA</a>) to manage parallel grid and vectors</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDACreate1d.html">DMDACreate1d</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DM_BOUNDARY_NONE</a></span><span class="p">,</span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMSetFromOptions.html">DMSetFromOptions</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMSetUp.html">DMSetUp</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Extract global and local vectors from <a href="../manualpages/DMDA/DMDA.html">DMDA</a>; then duplicate for remaining</span>
<span class="cm">     vectors that are the same types</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">r</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">F</span><span class="p">));</span>
<span class="w">  </span><span class="n">ctx</span><span class="p">.</span><span class="n">F</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">F</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">U</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set function evaluation routine and vector.  Whenever the nonlinear</span>
<span class="cm">     solver needs to compute the nonlinear function, it will call this</span>
<span class="cm">     routine.</span>
<span class="cm">      - Note that the final routine argument is the user-defined</span>
<span class="cm">        context that provides application-specific data for the</span>
<span class="cm">        function evaluation routine.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="n">FormFunction</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Create matrix data structure; set Jacobian evaluation routine</span>
<span class="cm">     - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">J</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetSizes.html">MatSetSizes</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span><span class="p">,</span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="w"> </span><span class="n">N</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetFromOptions.html">MatSetFromOptions</a></span><span class="p">(</span><span class="n">J</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSeqAIJSetPreallocation.html">MatSeqAIJSetPreallocation</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatMPIAIJSetPreallocation.html">MatMPIAIJSetPreallocation</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set Jacobian matrix data structure and default Jacobian evaluation</span>
<span class="cm">     routine.  Whenever the nonlinear solver needs to compute the</span>
<span class="cm">     Jacobian matrix, it will call this routine.</span>
<span class="cm">      - Note that the final routine argument is the user-defined</span>
<span class="cm">        context that provides application-specific data for the</span>
<span class="cm">        Jacobian evaluation routine.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="n">FormJacobian</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Optionally allow user-provided preconditioner</span>
<span class="cm">   */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsHasName.html">PetscOptionsHasName</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-user_precond&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">flg</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">flg</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </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/PC/PC.html">PC</a></span><span class="w">  </span><span class="n">pc</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetKSP.html">SNESGetKSP</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</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="w"> </span><span class="o">&amp;</span><span class="n">pc</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></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="w"> </span><span class="n"><a href="../manualpages/PC/PCSHELL.html">PCSHELL</a></span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PCShellSetApply.html">PCShellSetApply</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="w"> </span><span class="n">MatrixFreePreconditioner</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Customize nonlinear solver; set runtime options</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set an optional user-defined monitoring routine</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Viewer/PetscViewerDrawOpen.html">PetscViewerDrawOpen</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="mi">400</span><span class="p">,</span><span class="w"> </span><span class="mi">400</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">monP</span><span class="p">.</span><span class="n">viewer</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESMonitorSet.html">SNESMonitorSet</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n">Monitor</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">monP</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set names for some vectors to facilitate monitoring (optional)</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectSetName.html">PetscObjectSetName</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">x</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Approximate Solution&quot;</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectSetName.html">PetscObjectSetName</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">U</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Exact Solution&quot;</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set <a href="../manualpages/SNES/SNES.html">SNES</a>/<a href="../manualpages/KSP/KSP.html">KSP</a>/<a href="../manualpages/KSP/KSP.html">KSP</a>/<a href="../manualpages/PC/PC.html">PC</a> runtime options, e.g.,</span>
<span class="cm">         -snes_view -snes_monitor -ksp_type &lt;ksp&gt; -pc_type &lt;pc&gt;</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetFromOptions.html">SNESSetFromOptions</a></span><span class="p">(</span><span class="n">snes</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set an optional user-defined routine to check the validity of candidate</span>
<span class="cm">     iterates that are determined by line search methods</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetLineSearch.html">SNESGetLineSearch</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">linesearch</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsHasName.html">PetscOptionsHasName</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-post_check_iterates&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">post_check</span><span class="p">));</span>

<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">post_check</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Activating post step checking routine</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearchSetPostCheck.html">SNESLineSearchSetPostCheck</a></span><span class="p">(</span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="n">PostCheck</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">checkP</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">checkP</span><span class="p">.</span><span class="n">last_step</span><span class="p">));</span>

<span class="w">    </span><span class="n">checkP</span><span class="p">.</span><span class="n">tolerance</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span>
<span class="w">    </span><span class="n">checkP</span><span class="p">.</span><span class="n">user</span><span class="w">      </span><span class="o">=</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">;</span>

<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsGetReal.html">PetscOptionsGetReal</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-check_tol&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">checkP</span><span class="p">.</span><span class="n">tolerance</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsHasName.html">PetscOptionsHasName</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-post_setsubksp&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">post_setsubksp</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">post_setsubksp</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Activating post setsubksp</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearchSetPostCheck.html">SNESLineSearchSetPostCheck</a></span><span class="p">(</span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="n">PostSetSubKSP</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">checkP1</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsHasName.html">PetscOptionsHasName</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-pre_check_iterates&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">pre_check</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">pre_check</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Activating pre step checking routine</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearchSetPreCheck.html">SNESLineSearchSetPreCheck</a></span><span class="p">(</span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="n">PreCheck</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">checkP</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Print parameters used for convergence testing (optional) ... just</span>
<span class="cm">     to demonstrate this routine; this information is also printed with</span>
<span class="cm">     the option -snes_view</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetTolerances.html">SNESGetTolerances</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">abstol</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">rtol</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">stol</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">maxit</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">maxf</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;atol=%g, rtol=%g, stol=%g, maxit=%&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;, maxf=%&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">abstol</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">rtol</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">stol</span><span class="p">,</span><span class="w"> </span><span class="n">maxit</span><span class="p">,</span><span class="w"> </span><span class="n">maxf</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Initialize application:</span>
<span class="cm">     Store right-hand side of PDE and exact solution</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get local grid boundaries (for 1-dimensional <a href="../manualpages/DMDA/DMDA.html">DMDA</a>):</span>
<span class="cm">       xs, xm - starting grid index, width of local grid (no ghost points)</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetCorners.html">DMDAGetCorners</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xm</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get pointers to vector data</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">FF</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">U</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">UU</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Compute local vector entries</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n">xp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ctx</span><span class="p">.</span><span class="n">h</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xs</span><span class="p">;</span>
<span class="w">  </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xs</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="o">++</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n">FF</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">6.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xp</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">PetscPowScalar</span><span class="p">(</span><span class="n">xp</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">1.</span><span class="n">e</span><span class="mi">-12</span><span class="p">,</span><span class="w"> </span><span class="mf">6.0</span><span class="p">);</span><span class="w"> </span><span class="cm">/* +1.e-12 is to prevent 0^6 */</span>
<span class="w">    </span><span class="n">UU</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xp</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xp</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xp</span><span class="p">;</span>
<span class="w">    </span><span class="n">xp</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">ctx</span><span class="p">.</span><span class="n">h</span><span class="p">;</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Restore vectors</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">FF</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">U</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">UU</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">viewinitial</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecView.html">VecView</a></span><span class="p">(</span><span class="n">U</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecView.html">VecView</a></span><span class="p">(</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Evaluate initial guess; then solve nonlinear system</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Note: The user should initialize the vector, x, with the initial guess</span>
<span class="cm">     for the nonlinear solver prior to calling <a href="../manualpages/SNES/SNESSolve.html">SNESSolve</a>().  In particular,</span>
<span class="cm">     to employ an initial guess of zero, the user should explicitly set</span>
<span class="cm">     this vector to zero by calling <a href="../manualpages/Vec/VecSet.html">VecSet</a>().</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n">FormInitialGuess</span><span class="p">(</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSolve.html">SNESSolve</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetIterationNumber.html">SNESGetIterationNumber</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">its</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Number of <a href="../manualpages/SNES/SNES.html">SNES</a> iterations = %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">its</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -</span>
<span class="cm">     Check solution and clean up</span>
<span class="cm">   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Check the error</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecAXPY.html">VecAXPY</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">none</span><span class="p">,</span><span class="w"> </span><span class="n">U</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecNorm.html">VecNorm</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_2.html">NORM_2</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">norm</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Norm of error %g Iterations %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">norm</span><span class="p">,</span><span class="w"> </span><span class="n">its</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">ctx</span><span class="p">.</span><span class="n">sjerr</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/SNES/SNESType.html">SNESType</a></span><span class="w"> </span><span class="n">snestype</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetType.html">SNESGetType</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">snestype</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;<a href="../manualpages/SNES/SNES.html">SNES</a> Type %s</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">snestype</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Free work space.  All PETSc objects should be destroyed when they</span>
<span class="cm">     are no longer needed.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Viewer/PetscViewerDestroy.html">PetscViewerDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">monP</span><span class="p">.</span><span class="n">viewer</span><span class="p">));</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">post_check</span><span class="p">)</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">checkP</span><span class="p">.</span><span class="n">last_step</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">r</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">U</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">F</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatDestroy.html">MatDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">J</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESDestroy.html">SNESDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">snes</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMDestroy.html">DMDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">ctx</span><span class="p">.</span><span class="n">da</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a></span><span class="p">());</span>
<span class="w">  </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   FormInitialGuess - Computes initial guess.</span>

<span class="cm">   Input/Output Parameter:</span>
<span class="cm">.  x - the solution vector</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormInitialGuess</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="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">pfive</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">.50</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecSet.html">VecSet</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">pfive</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   FormFunction - Evaluates nonlinear function, F(x).</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">.  snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">.  x - input vector</span>
<span class="cm">.  ctx - optional user-defined context, as set by <a href="../manualpages/SNES/SNESSetFunction.html">SNESSetFunction</a>()</span>

<span class="cm">   Output Parameter:</span>
<span class="cm">.  f - function vector</span>

<span class="cm">   Note:</span>
<span class="cm">   The user-defined context can contain any application-specific</span>
<span class="cm">   data needed for the function evaluation.</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormFunction</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</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="p">{</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w">    </span><span class="o">*</span><span class="n">user</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w">                 </span><span class="n">da</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">da</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">       </span><span class="o">*</span><span class="n">ff</span><span class="p">,</span><span class="w"> </span><span class="n">d</span><span class="p">;</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">FF</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">i</span><span class="p">,</span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">                </span><span class="n">xlocal</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGetLocalVector.html">DMGetLocalVector</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xlocal</span><span class="p">));</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Scatter ghost points to local vector, using the 2-step process</span>
<span class="cm">        <a href="../manualpages/DM/DMGlobalToLocalBegin.html">DMGlobalToLocalBegin</a>(), <a href="../manualpages/DM/DMGlobalToLocalEnd.html">DMGlobalToLocalEnd</a>().</span>
<span class="cm">     By placing code between these two statements, computations can</span>
<span class="cm">     be done while messages are in transition.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGlobalToLocalBegin.html">DMGlobalToLocalBegin</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n">xlocal</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGlobalToLocalEnd.html">DMGlobalToLocalEnd</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n">xlocal</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get pointers to vector data.</span>
<span class="cm">       - The vector xlocal includes ghost point; the vectors x and f do</span>
<span class="cm">         NOT include ghost points.</span>
<span class="cm">       - Using <a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a>() allows accessing the values using global ordering</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayRead.html">DMDAVecGetArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">xlocal</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayRead.html">DMDAVecGetArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">FF</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get local grid boundaries (for 1-dimensional <a href="../manualpages/DMDA/DMDA.html">DMDA</a>):</span>
<span class="cm">       xs, xm  - starting grid index, width of local grid (no ghost points)</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetCorners.html">DMDAGetCorners</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xm</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetInfo.html">DMDAGetInfo</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Set function values for boundary points; define local interior grid point range:</span>
<span class="cm">        xsi - starting interior grid index</span>
<span class="cm">        xei - ending interior grid index</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">xs</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* left boundary */</span>
<span class="w">    </span><span class="n">ff</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="w">    </span><span class="n">xs</span><span class="o">++</span><span class="p">;</span>
<span class="w">    </span><span class="n">xm</span><span class="o">--</span><span class="p">;</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">M</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* right boundary */</span>
<span class="w">    </span><span class="n">ff</span><span class="p">[</span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span>
<span class="w">    </span><span class="n">xm</span><span class="o">--</span><span class="p">;</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Compute function over locally owned part of the grid (interior points only)</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n">d</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">(</span><span class="n">user</span><span class="o">-&gt;</span><span class="n">h</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">h</span><span class="p">);</span>
<span class="w">  </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xs</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="o">++</span><span class="p">)</span><span class="w"> </span><span class="n">ff</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="p">(</span><span class="n">xx</span><span class="p">[</span><span class="n">i</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mf">2.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="n">i</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">])</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">FF</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Restore vectors</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">xlocal</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">FF</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMRestoreLocalVector.html">DMRestoreLocalVector</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xlocal</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   FormJacobian - Evaluates Jacobian matrix.</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">.  snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">.  x - input vector</span>
<span class="cm">.  dummy - optional user-defined context (not used here)</span>

<span class="cm">   Output Parameters:</span>
<span class="cm">.  jac - Jacobian matrix</span>
<span class="cm">.  B - optionally different preconditioning matrix</span>

<span class="cm">*/</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">FormJacobian</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">B</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="p">{</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="n">user</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">    </span><span class="o">*</span><span class="n">xx</span><span class="p">,</span><span class="w"> </span><span class="n">d</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">[</span><span class="mi">3</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">i</span><span class="p">,</span><span class="w"> </span><span class="n">j</span><span class="p">[</span><span class="mi">3</span><span class="p">],</span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w">              </span><span class="n">da</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">da</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">user</span><span class="o">-&gt;</span><span class="n">sjerr</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESSetJacobianDomainError.html">SNESSetJacobianDomainError</a></span><span class="p">(</span><span class="n">snes</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Get pointer to vector data</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayRead.html">DMDAVecGetArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetCorners.html">DMDAGetCorners</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xm</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">    Get range of locally owned matrix</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetInfo.html">DMDAGetInfo</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Determine starting and ending local indices for interior grid points.</span>
<span class="cm">     Set Jacobian entries for boundary points.</span>
<span class="cm">  */</span>

<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">xs</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* left boundary */</span>
<span class="w">    </span><span class="n">i</span><span class="w">    </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="w">    </span><span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span>

<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">));</span>
<span class="w">    </span><span class="n">xs</span><span class="o">++</span><span class="p">;</span>
<span class="w">    </span><span class="n">xm</span><span class="o">--</span><span class="p">;</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">M</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="cm">/* right boundary */</span>
<span class="w">    </span><span class="n">i</span><span class="w">    </span><span class="o">=</span><span class="w"> </span><span class="n">M</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
<span class="w">    </span><span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">));</span>
<span class="w">    </span><span class="n">xm</span><span class="o">--</span><span class="p">;</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Interior grid points</span>
<span class="cm">      - Note that in this case we set all elements for a particular</span>
<span class="cm">        row at once.</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n">d</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">(</span><span class="n">user</span><span class="o">-&gt;</span><span class="n">h</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">h</span><span class="p">);</span>
<span class="w">  </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xs</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="o">++</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n">j</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
<span class="w">    </span><span class="n">j</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">i</span><span class="p">;</span>
<span class="w">    </span><span class="n">j</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span>
<span class="w">    </span><span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">A</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d</span><span class="p">;</span>
<span class="w">    </span><span class="n">A</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="w">        </span><span class="o">=</span><span class="w"> </span><span class="mf">-2.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">d</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">2.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xx</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">j</span><span class="p">,</span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Assemble matrix, using the 2-step process:</span>
<span class="cm">       <a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a>(), <a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a>().</span>
<span class="cm">     By placing code between these two statements, computations can be</span>
<span class="cm">     done while messages are in transition.</span>

<span class="cm">     Also, restore vector.</span>
<span class="cm">  */</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyBegin.html">MatAssemblyBegin</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatAssemblyEnd.html">MatAssemblyEnd</a></span><span class="p">(</span><span class="n">jac</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/MatAssemblyType.html">MAT_FINAL_ASSEMBLY</a></span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   Monitor - Optional user-defined monitoring routine that views the</span>
<span class="cm">   current iterate with an x-window plot. Set by <a href="../manualpages/SNES/SNESMonitorSet.html">SNESMonitorSet</a>().</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">   snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">   its - iteration number</span>
<span class="cm">   norm - 2-norm function value (may be estimated)</span>
<span class="cm">   ctx - optional user-defined context for private data for the</span>
<span class="cm">         monitor routine, as set by <a href="../manualpages/SNES/SNESMonitorSet.html">SNESMonitorSet</a>()</span>

<span class="cm">   Note:</span>
<span class="cm">   See the manpage for <a href="../manualpages/Viewer/PetscViewerDrawOpen.html">PetscViewerDrawOpen</a>() for useful runtime options,</span>
<span class="cm">   such as -nox to deactivate all x-window output.</span>
<span class="cm"> */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">Monitor</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">its</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">fnorm</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="p">{</span>
<span class="w">  </span><span class="n">MonitorCtx</span><span class="w"> </span><span class="o">*</span><span class="n">monP</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">MonitorCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </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="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;iter = %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;,<a href="../manualpages/SNES/SNES.html">SNES</a> Function norm %g</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">its</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">fnorm</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetSolution.html">SNESGetSolution</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">x</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecView.html">VecView</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">monP</span><span class="o">-&gt;</span><span class="n">viewer</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   PreCheck - Optional user-defined routine that checks the validity of</span>
<span class="cm">   candidate steps of a line search method.  Set by <a href="../manualpages/SNES/SNESLineSearchSetPreCheck.html">SNESLineSearchSetPreCheck</a>().</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">   snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">   xcurrent - current solution</span>
<span class="cm">   y - search direction and length</span>

<span class="cm">   Output Parameters:</span>
<span class="cm">   y         - proposed step (search direction and length) (possibly changed)</span>
<span class="cm">   changed_y - tells if the step has changed or not</span>
<span class="cm"> */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PreCheck</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">xcurrent</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="n">changed_y</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="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="o">*</span><span class="n">changed_y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   PostCheck - Optional user-defined routine that checks the validity of</span>
<span class="cm">   candidate steps of a line search method.  Set by <a href="../manualpages/SNES/SNESLineSearchSetPostCheck.html">SNESLineSearchSetPostCheck</a>().</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">   snes - the <a href="../manualpages/SNES/SNES.html">SNES</a> context</span>
<span class="cm">   ctx  - optional user-defined context for private data for the</span>
<span class="cm">          monitor routine, as set by <a href="../manualpages/SNES/SNESLineSearchSetPostCheck.html">SNESLineSearchSetPostCheck</a>()</span>
<span class="cm">   xcurrent - current solution</span>
<span class="cm">   y - search direction and length</span>
<span class="cm">   x    - the new candidate iterate</span>

<span class="cm">   Output Parameters:</span>
<span class="cm">   y    - proposed step (search direction and length) (possibly changed)</span>
<span class="cm">   x    - current iterate (possibly modified)</span>

<span class="cm"> */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PostCheck</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">xcurrent</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="n">changed_y</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="n">changed_x</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="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">i</span><span class="p">,</span><span class="w"> </span><span class="n">iter</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span>
<span class="w">  </span><span class="n">StepCheckCtx</span><span class="w">   </span><span class="o">*</span><span class="n">check</span><span class="p">;</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="n">user</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">    </span><span class="o">*</span><span class="n">xa</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">xa_last</span><span class="p">,</span><span class="w"> </span><span class="n">tmp</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">rdiff</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w">              </span><span class="n">da</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w">            </span><span class="n">snes</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="o">*</span><span class="n">changed_x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">;</span>
<span class="w">  </span><span class="o">*</span><span class="n">changed_y</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearchGetSNES.html">SNESLineSearchGetSNES</a></span><span class="p">(</span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">snes</span><span class="p">));</span>
<span class="w">  </span><span class="n">check</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">StepCheckCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </span><span class="n">user</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">user</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetIterationNumber.html">SNESGetIterationNumber</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">iter</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* iteration 1 indicates we are working on the second iteration */</span>
<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">iter</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n">da</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">da</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;Checking candidate step at iteration %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot; with tolerance %g</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">iter</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">check</span><span class="o">-&gt;</span><span class="n">tolerance</span><span class="p">));</span>

<span class="w">    </span><span class="cm">/* Access local array data */</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">last_step</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xa_last</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xa</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetCorners.html">DMDAGetCorners</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xm</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>

<span class="w">    </span><span class="cm">/*</span>
<span class="cm">       If we fail the user-defined check for validity of the candidate iterate,</span>
<span class="cm">       then modify the iterate as we like.  (Note that the particular modification</span>
<span class="cm">       below is intended simply to demonstrate how to manipulate this data, not</span>
<span class="cm">       as a meaningful or appropriate choice.)</span>
<span class="cm">    */</span>
<span class="w">    </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xs</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">xs</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span><span class="w"> </span><span class="n">i</span><span class="o">++</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">      </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">PetscAbsScalar</span><span class="p">(</span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">]))</span><span class="w"> </span><span class="n">rdiff</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">tolerance</span><span class="p">;</span>
<span class="w">      </span><span class="k">else</span><span class="w"> </span><span class="n">rdiff</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PetscAbsScalar</span><span class="p">((</span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">xa_last</span><span class="p">[</span><span class="n">i</span><span class="p">])</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
<span class="w">      </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">rdiff</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">tolerance</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">        </span><span class="n">tmp</span><span class="w">        </span><span class="o">=</span><span class="w"> </span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="w">        </span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w">      </span><span class="o">=</span><span class="w"> </span><span class="mf">.5</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="p">(</span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xa_last</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
<span class="w">        </span><span class="o">*</span><span class="n">changed_x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span><span class="p">;</span>
<span class="w">        </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;  Altering entry %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;: x=%g, x_last=%g, diff=%g, x_new=%g</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">PetscAbsScalar</span><span class="p">(</span><span class="n">tmp</span><span class="p">),</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">PetscAbsScalar</span><span class="p">(</span><span class="n">xa_last</span><span class="p">[</span><span class="n">i</span><span class="p">]),</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">rdiff</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">PetscAbsScalar</span><span class="p">(</span><span class="n">xa</span><span class="p">[</span><span class="n">i</span><span class="p">])));</span>
<span class="w">      </span><span class="p">}</span>
<span class="w">    </span><span class="p">}</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">last_step</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xa_last</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xa</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecCopy.html">VecCopy</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">last_step</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   PostSetSubKSP - Optional user-defined routine that reset SubKSP options when hierarchical bjacobi <a href="../manualpages/PC/PC.html">PC</a> is used</span>
<span class="cm">   e.g,</span>
<span class="cm">     mpiexec -n 8 ./ex3 -nox -n 10000 -ksp_type fgmres -pc_type bjacobi -pc_bjacobi_blocks 4 -sub_ksp_type gmres -sub_ksp_max_it 3 -post_setsubksp -sub_ksp_rtol 1.e-16</span>
<span class="cm">   Set by <a href="../manualpages/SNES/SNESLineSearchSetPostCheck.html">SNESLineSearchSetPostCheck</a>().</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">   linesearch - the LineSearch context</span>
<span class="cm">   xcurrent - current solution</span>
<span class="cm">   y - search direction and length</span>
<span class="cm">   x    - the new candidate iterate</span>

<span class="cm">   Output Parameters:</span>
<span class="cm">   y    - proposed step (search direction and length) (possibly changed)</span>
<span class="cm">   x    - current iterate (possibly modified)</span>

<span class="cm"> */</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PostSetSubKSP</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearch.html">SNESLineSearch</a></span><span class="w"> </span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">xcurrent</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="w"> </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="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="n">changed_y</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="n">changed_x</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="p">{</span>
<span class="w">  </span><span class="n">SetSubKSPCtx</span><span class="w"> </span><span class="o">*</span><span class="n">check</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">iter</span><span class="p">,</span><span class="w"> </span><span class="n">its</span><span class="p">,</span><span class="w"> </span><span class="n">sub_its</span><span class="p">,</span><span class="w"> </span><span class="n">maxit</span><span class="p">;</span>
<span class="w">  </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">sub_ksp</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">sub_ksps</span><span class="p">;</span>
<span class="w">  </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="w">  </span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w">     </span><span class="n">ksp_ratio</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w">          </span><span class="n">snes</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESLineSearchGetSNES.html">SNESLineSearchGetSNES</a></span><span class="p">(</span><span class="n">linesearch</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">snes</span><span class="p">));</span>
<span class="w">  </span><span class="n">check</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">SetSubKSPCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetIterationNumber.html">SNESGetIterationNumber</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">iter</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNESGetKSP.html">SNESGetKSP</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ksp</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</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="w"> </span><span class="o">&amp;</span><span class="n">pc</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PC/PCBJacobiGetSubKSP.html">PCBJacobiGetSubKSP</a></span><span class="p">(</span><span class="n">pc</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">sub_ksps</span><span class="p">));</span>
<span class="w">  </span><span class="n">sub_ksp</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">sub_ksps</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSPGetIterationNumber.html">KSPGetIterationNumber</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">its</span><span class="p">));</span><span class="w">         </span><span class="cm">/* outer <a href="../manualpages/KSP/KSP.html">KSP</a> iteration number */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSPGetIterationNumber.html">KSPGetIterationNumber</a></span><span class="p">(</span><span class="n">sub_ksp</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">sub_its</span><span class="p">));</span><span class="w"> </span><span class="cm">/* inner <a href="../manualpages/KSP/KSP.html">KSP</a> iteration number */</span>

<span class="w">  </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">iter</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;    ...PostCheck snes iteration %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;, ksp_it %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot; %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;, subksp_it %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">iter</span><span class="p">,</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">its0</span><span class="p">,</span><span class="w"> </span><span class="n">its</span><span class="p">,</span><span class="w"> </span><span class="n">sub_its</span><span class="p">));</span>
<span class="w">    </span><span class="n">ksp_ratio</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">)</span><span class="n">its</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">its0</span><span class="p">;</span>
<span class="w">    </span><span class="n">maxit</span><span class="w">     </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">)(</span><span class="n">ksp_ratio</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">sub_its</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mf">0.5</span><span class="p">);</span>
<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">maxit</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="mi">2</span><span class="p">)</span><span class="w"> </span><span class="n">maxit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSPSetTolerances.html">KSPSetTolerances</a></span><span class="p">(</span><span class="n">sub_ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PETSC_CURRENT.html">PETSC_CURRENT</a></span><span class="p">,</span><span class="w"> </span><span class="n">maxit</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscPrintf.html">PetscPrintf</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="p">,</span><span class="w"> </span><span class="s">&quot;    ...ksp_ratio %g, new maxit %&quot;</span><span class="w"> </span><span class="n">PetscInt_FMT</span><span class="w"> </span><span class="s">&quot;</span><span class="se">\n\n</span><span class="s">&quot;</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="n">ksp_ratio</span><span class="p">,</span><span class="w"> </span><span class="n">maxit</span><span class="p">));</span>
<span class="w">  </span><span class="p">}</span>
<span class="w">  </span><span class="n">check</span><span class="o">-&gt;</span><span class="n">its0</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">its</span><span class="p">;</span><span class="w"> </span><span class="cm">/* save current outer <a href="../manualpages/KSP/KSP.html">KSP</a> iteration number */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

<span class="cm">/* ------------------------------------------------------------------- */</span>
<span class="cm">/*</span>
<span class="cm">   MatrixFreePreconditioner - This routine demonstrates the use of a</span>
<span class="cm">   user-provided preconditioner.  This code implements just the null</span>
<span class="cm">   preconditioner, which of course is not recommended for general use.</span>

<span class="cm">   Input Parameters:</span>
<span class="cm">+  pc - preconditioner</span>
<span class="cm">-  x - input vector</span>

<span class="cm">   Output Parameter:</span>
<span class="cm">.  y - preconditioned vector</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">MatrixFreePreconditioner</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="w"> </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="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecCopy.html">VecCopy</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">y</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>

</pre></div>
</div>
</div>
<p>Table <a class="reference internal" href="#tab-jacobians"><span class="std std-ref">Jacobian Options</span></a> summarizes the various matrix situations
that <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> supports. In particular, different linear system matrices
and preconditioning matrices are allowed, as well as both matrix-free
and application-provided preconditioners. If <a class="reference internal" href="#snes-ex3"><span class="std std-ref">ex3.c</span></a> is run with
the options <code class="docutils notranslate"><span class="pre">-snes_mf</span></code> and <code class="docutils notranslate"><span class="pre">-user_precond</span></code> then it uses a
matrix-free application of the matrix-vector multiple and a user
provided matrix-free Jacobian.</p>
<table class="table" id="tab-jacobians">
<caption><span class="caption-number">Table 12 </span><span class="caption-text">Jacobian Options</span><a class="headerlink" href="#tab-jacobians" title="Link to this table">#</a></caption>
<tbody>
<tr class="row-odd"><td><p>Matrix Use</p></td>
<td><p>Conventional Matrix Formats</p></td>
<td><p>Matrix-free versions</p></td>
</tr>
<tr class="row-even"><td><p>Jacobian Matrix</p></td>
<td><p>Create matrix with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a>()</span></code><span class="math">\(^*\)</span>.  Assemble matrix with user-defined routine <span class="math">\(^\dagger\)</span></p></td>
<td><p>Create matrix with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateShell.html">MatCreateShell</a>()</span></code>.  Use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatShellSetOperation.html">MatShellSetOperation</a>()</span></code> to set various matrix actions, or use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateMFFD.html">MatCreateMFFD</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/MatCreateSNESMF.html">MatCreateSNESMF</a>()</span></code>.</p></td>
</tr>
<tr class="row-odd"><td><p>Preconditioning Matrix</p></td>
<td><p>Create matrix with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a>()</span></code><span class="math">\(^*\)</span>.  Assemble matrix with user-defined routine <span class="math">\(^\dagger\)</span></p></td>
<td><p>Use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESGetKSP.html">SNESGetKSP</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGetPC.html">KSPGetPC</a>()</span></code> to access the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code>, then use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCSetType.html">PCSetType</a>(pc,</span> <span class="pre"><a href="../manualpages/PC/PCSHELL.html">PCSHELL</a>)</span></code> followed by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCShellSetApply.html">PCShellSetApply</a>()</span></code>.</p></td>
</tr>
</tbody>
</table>
<p><span class="math">\(^*\)</span> Use either the generic <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreate.html">MatCreate</a>()</span></code> or a format-specific variant such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateAIJ.html">MatCreateAIJ</a>()</span></code>.</p>
<p><span class="math">\(^\dagger\)</span> Set user-defined matrix formation routine with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a>()</span></code> or with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> variant such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/DMDASNESSetJacobianLocal.html">DMDASNESSetJacobianLocal</a>()</span></code></p>
<p>SNES also provides some less well-integrated code to apply matrix-free finite differencing using an automatically computed measurement of the
noise of the functions. This can be selected with <code class="docutils notranslate"><span class="pre">-snes_mf_version</span> <span class="pre">2</span></code>; it does not use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatCreateMFFD.html">MatCreateMFFD</a>()</span></code> but has similar options that start with
<code class="docutils notranslate"><span class="pre">-snes_mf_</span></code> instead of <code class="docutils notranslate"><span class="pre">-mat_mffd_</span></code>. Note that this alternative prefix <strong>only</strong> works for version 2 differencing.</p>
</section>
<section id="finite-difference-jacobian-approximations">
<span id="sec-fdmatrix"></span><h2>Finite Difference Jacobian Approximations<a class="headerlink" href="#finite-difference-jacobian-approximations" title="Link to this heading">#</a></h2>
<p>PETSc provides some tools to help approximate the Jacobian matrices
efficiently via finite differences. These tools are intended for use in
certain situations where one is unable to compute Jacobian matrices
analytically, and matrix-free methods do not work well without a
preconditioner, due to very poor conditioning. The approximation
requires several steps:</p>
<ul class="simple">
<li><p>First, one colors the columns of the (not yet built) Jacobian matrix,
so that columns of the same color do not share any common rows.</p></li>
<li><p>Next, one creates a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatFDColoring.html">MatFDColoring</a></span></code> data structure that will be
used later in actually computing the Jacobian.</p></li>
<li><p>Finally, one tells the nonlinear solvers of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> to use the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESComputeJacobianDefaultColor.html">SNESComputeJacobianDefaultColor</a>()</span></code> routine to compute the
Jacobians.</p></li>
</ul>
<p>A code fragment that demonstrates this process is given below.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISColoring.html">ISColoring</a></span><span class="w">    </span><span class="n">iscoloring</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Mat/MatFDColoring.html">MatFDColoring</a></span><span class="w"> </span><span class="n">fdcoloring</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Mat/MatColoring.html">MatColoring</a></span><span class="w">   </span><span class="n">coloring</span><span class="p">;</span>

<span class="cm">/*</span>
<span class="cm">  This initializes the nonzero structure of the Jacobian. This is artificial</span>
<span class="cm">  because clearly if we had a routine to compute the Jacobian we wouldn&#39;t</span>
<span class="cm">  need to use finite differences.</span>
<span class="cm">*/</span>
<span class="n">FormJacobian</span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">user</span><span class="p">);</span>

<span class="cm">/*</span>
<span class="cm">   Color the matrix, i.e. determine groups of columns that share no common</span>
<span class="cm">  rows. These columns in the Jacobian can all be computed simultaneously.</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/MatGraphOperations/MatColoringCreate.html">MatColoringCreate</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">coloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatGraphOperations/MatColoringSetType.html">MatColoringSetType</a></span><span class="p">(</span><span class="n">coloring</span><span class="p">,</span><span class="n"><a href="../manualpages/MatGraphOperations/MATCOLORINGSL.html">MATCOLORINGSL</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatGraphOperations/MatColoringSetFromOptions.html">MatColoringSetFromOptions</a></span><span class="p">(</span><span class="n">coloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatGraphOperations/MatColoringApply.html">MatColoringApply</a></span><span class="p">(</span><span class="n">coloring</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">iscoloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatGraphOperations/MatColoringDestroy.html">MatColoringDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">coloring</span><span class="p">);</span>
<span class="cm">/*</span>
<span class="cm">   Create the data structure that <a href="../manualpages/SNES/SNESComputeJacobianDefaultColor.html">SNESComputeJacobianDefaultColor</a>() uses</span>
<span class="cm">   to compute the actual Jacobians via finite differences.</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/MatFD/MatFDColoringCreate.html">MatFDColoringCreate</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="n">iscoloring</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">fdcoloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISColoringDestroy.html">ISColoringDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">iscoloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatFD/MatFDColoringSetFunction.html">MatFDColoringSetFunction</a></span><span class="p">(</span><span class="n">fdcoloring</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="p">)(</span><span class="kt">void</span><span class="p">))</span><span class="n">FormFunction</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">user</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatFD/MatFDColoringSetFromOptions.html">MatFDColoringSetFromOptions</a></span><span class="p">(</span><span class="n">fdcoloring</span><span class="p">);</span>

<span class="cm">/*</span>
<span class="cm">  Tell <a href="../manualpages/SNES/SNES.html">SNES</a> to use the routine <a href="../manualpages/SNES/SNESComputeJacobianDefaultColor.html">SNESComputeJacobianDefaultColor</a>()</span>
<span class="cm">  to compute Jacobians.</span>
<span class="cm">*/</span>
<span class="n"><a href="../manualpages/SNES/SNESSetJacobian.html">SNESSetJacobian</a></span><span class="p">(</span><span class="n">snes</span><span class="p">,</span><span class="n">J</span><span class="p">,</span><span class="n">J</span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESComputeJacobianDefaultColor.html">SNESComputeJacobianDefaultColor</a></span><span class="p">,</span><span class="n">fdcoloring</span><span class="p">);</span>
</pre></div>
</div>
<p>Of course, we are cheating a bit. If we do not have an analytic formula
for computing the Jacobian, then how do we know what its nonzero
structure is so that it may be colored? Determining the structure is
problem dependent, but fortunately, for most structured grid problems
(the class of problems for which PETSc was originally designed) if one
knows the stencil used for the nonlinear function one can usually fairly
easily obtain an estimate of the location of nonzeros in the matrix.
This is harder in the unstructured case, but one typically knows where the nonzero entries are from the mesh topology and distribution of degrees of freedom.
If using <code class="docutils notranslate"><span class="pre">DMPlex</span></code> (<a class="reference internal" href="dmplex.html#ch-unstructured"><span class="std std-ref">DMPlex: Unstructured Grids</span></a>) for unstructured meshes, the nonzero locations will be identified in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateMatrix.html">DMCreateMatrix</a>()</span></code> and the procedure above can be used.
Most external packages for unstructured meshes have similar functionality.</p>
<p>One need not necessarily use a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatColoring.html">MatColoring</a></span></code> object to determine a
coloring. For example, if a grid can be colored directly (without using
the associated matrix), then that coloring can be provided to
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatFD/MatFDColoringCreate.html">MatFDColoringCreate</a>()</span></code>. Note that the user must always preset the
nonzero structure in the matrix regardless of which coloring routine is
used.</p>
<p>PETSc provides the following coloring algorithms, which can be selected using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MatColoringSetType.html">MatColoringSetType</a>()</span></code> or via the command line argument <code class="docutils notranslate"><span class="pre">-mat_coloring_type</span></code>.</p>
<table class="table">
<thead>
<tr class="row-odd"><th class="head"><p>Algorithm</p></th>
<th class="head"><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatColoringType.html">MatColoringType</a></span></code></p></th>
<th class="head"><p><code class="docutils notranslate"><span class="pre">-mat_coloring_type</span></code></p></th>
<th class="head"><p>Parallel</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>smallest-last <span id="id1">[<a class="reference internal" href="#id2283" title="Jorge J. Moré, Danny C. Sorenson, Burton S. Garbow, and Kenneth E. Hillstrom. The MINPACK project. In Wayne R. Cowell, editor, Sources and Development of Mathematical Software, 88–111. 1984.">MoreSGH84</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGSL.html">MATCOLORINGSL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">sl</span></code></p></td>
<td><p>No</p></td>
</tr>
<tr class="row-odd"><td><p>largest-first <span id="id2">[<a class="reference internal" href="#id2283" title="Jorge J. Moré, Danny C. Sorenson, Burton S. Garbow, and Kenneth E. Hillstrom. The MINPACK project. In Wayne R. Cowell, editor, Sources and Development of Mathematical Software, 88–111. 1984.">MoreSGH84</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGLF.html">MATCOLORINGLF</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">lf</span></code></p></td>
<td><p>No</p></td>
</tr>
<tr class="row-even"><td><p>incidence-degree <span id="id3">[<a class="reference internal" href="#id2283" title="Jorge J. Moré, Danny C. Sorenson, Burton S. Garbow, and Kenneth E. Hillstrom. The MINPACK project. In Wayne R. Cowell, editor, Sources and Development of Mathematical Software, 88–111. 1984.">MoreSGH84</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGID.html">MATCOLORINGID</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">id</span></code></p></td>
<td><p>No</p></td>
</tr>
<tr class="row-odd"><td><p>Jones-Plassmann <span id="id4">[<a class="reference internal" href="../manualpages/MatGraphOperations/MATCOLORINGJP.html#id1264" title="Mark T. Jones and Paul E. Plassmann. A parallel graph coloring heuristic. SIAM J. Sci. Comput., 14(3):654-669, 1993.">JP93</a>]</span></p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGJP.html">MATCOLORINGJP</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">jp</span></code></p></td>
<td><p>Yes</p></td>
</tr>
<tr class="row-even"><td><p>Greedy</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGGREEDY.html">MATCOLORINGGREEDY</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">greedy</span></code></p></td>
<td><p>Yes</p></td>
</tr>
<tr class="row-odd"><td><p>Natural (1 color per column)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGNATURAL.html">MATCOLORINGNATURAL</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">natural</span></code></p></td>
<td><p>Yes</p></td>
</tr>
<tr class="row-even"><td><p>Power (<span class="math">\(A^k\)</span> followed by 1-coloring)</p></td>
<td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGPOWER.html">MATCOLORINGPOWER</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">power</span></code></p></td>
<td><p>Yes</p></td>
</tr>
</tbody>
</table>
<p>As for the matrix-free computation of Jacobians (<a class="reference internal" href="#sec-nlmatrixfree"><span class="std std-ref">Matrix-Free Methods</span></a>), two parameters affect the accuracy of the
finite difference Jacobian approximation. These are set with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/MatFD/MatFDColoringSetParameters.html">MatFDColoringSetParameters</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Mat/MatFDColoring.html">MatFDColoring</a></span><span class="w"> </span><span class="n">fdcoloring</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">rerror</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">umin</span><span class="p">);</span>
</pre></div>
</div>
<p>The parameter <code class="docutils notranslate"><span class="pre">rerror</span></code> is the square root of the relative error in the
function evaluations, <span class="math">\(e_{rel}\)</span>; the default is the square root of
machine epsilon (about <span class="math">\(10^{-8}\)</span> in double precision), which
assumes that the functions are evaluated approximately to floating-point
precision accuracy. The second parameter, <code class="docutils notranslate"><span class="pre">umin</span></code>, is a bit more
involved; its default is <span class="math">\(10^{-6}\)</span>. Column <span class="math">\(i\)</span> of the
Jacobian matrix (denoted by <span class="math">\(F_{:i}\)</span>) is approximated by the
formula</p>
<div class="math">
\[
F'_{:i} \approx \frac{F(u + h*dx_{i}) - F(u)}{h}
\]</div>
<p>where <span class="math">\(h\)</span> is computed via:</p>
<div class="math">
\[
h = e_{\text{rel}} \cdot \begin{cases}
u_{i}             &    \text{if $|u_{i}| > u_{\min}$} \\
u_{\min} \cdot \operatorname{sign}(u_{i})  & \text{otherwise}.
\end{cases}
\]</div>
<p>for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMFFD_DS.html">MATMFFD_DS</a></span></code> or:</p>
<div class="math">
\[
h = e_{\text{rel}} \sqrt{\|u\|}
\]</div>
<p>for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMFFD_WP.html">MATMFFD_WP</a></span></code> (default). These parameters may be set from the options
database with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">mat_fd_coloring_err</span><span class="w"> </span><span class="o">&lt;</span><span class="n">err</span><span class="o">&gt;</span>
<span class="o">-</span><span class="n">mat_fd_coloring_umin</span><span class="w"> </span><span class="o">&lt;</span><span class="n">umin</span><span class="o">&gt;</span>
<span class="o">-</span><span class="n">mat_fd_type</span><span class="w"> </span><span class="o">&lt;</span><span class="n">htype</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Note that <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatColoring.html">MatColoring</a></span></code> type <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGSL.html">MATCOLORINGSL</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGLF.html">MATCOLORINGLF</a></span></code>, and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGID.html">MATCOLORINGID</a></span></code> are sequential algorithms. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGJP.html">MATCOLORINGJP</a></span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatGraphOperations/MATCOLORINGGREEDY.html">MATCOLORINGGREEDY</a></span></code> are parallel algorithms, although in practice they
may create more colors than the sequential algorithms. If one computes
the coloring <code class="docutils notranslate"><span class="pre">iscoloring</span></code> reasonably with a parallel algorithm or by
knowledge of the discretization, the routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatFD/MatFDColoringCreate.html">MatFDColoringCreate</a>()</span></code>
is scalable. An example of this for 2D distributed arrays is given below
that uses the utility routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateColoring.html">DMCreateColoring</a>()</span></code>.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMCreateColoring.html">DMCreateColoring</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="n">IS_COLORING_GHOSTED</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">iscoloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatFD/MatFDColoringCreate.html">MatFDColoringCreate</a></span><span class="p">(</span><span class="n">J</span><span class="p">,</span><span class="n">iscoloring</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">fdcoloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/MatFD/MatFDColoringSetFromOptions.html">MatFDColoringSetFromOptions</a></span><span class="p">(</span><span class="n">fdcoloring</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISColoringDestroy.html">ISColoringDestroy</a></span><span class="p">(</span><span class="w"> </span><span class="o">&amp;</span><span class="n">iscoloring</span><span class="p">);</span>
</pre></div>
</div>
<p>Note that the routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/MatFD/MatFDColoringCreate.html">MatFDColoringCreate</a>()</span></code> currently is only
supported for the AIJ and BAIJ matrix formats.</p>
</section>
<section id="variational-inequalities">
<span id="sec-vi"></span><h2>Variational Inequalities<a class="headerlink" href="#variational-inequalities" title="Link to this heading">#</a></h2>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> can also solve (differential) variational inequalities with box (bound) constraints.
These are nonlinear algebraic systems with additional inequality
constraints on some or all of the variables:
<span class="math">\(L_i \le u_i \le H_i\)</span>. For example, the pressure variable cannot be negative.
Some, or all, of the lower bounds may be
negative infinity (indicated to PETSc with <code class="docutils notranslate"><span class="pre">SNES_VI_NINF</span></code>) and some, or
all, of the upper bounds may be infinity (indicated by <code class="docutils notranslate"><span class="pre">SNES_VI_INF</span></code>).
The commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESVISetVariableBounds.html">SNESVISetVariableBounds</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">L</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">H</span><span class="p">);</span>
<span class="n"><a href="../manualpages/SNES/SNESVISetComputeVariableBounds.html">SNESVISetComputeVariableBounds</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</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">compute</span><span class="p">)(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</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>are used to indicate that one is solving a variational inequality. Problems with box constraints can be solved with
the reduced space, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESVINEWTONRSLS.html">SNESVINEWTONRSLS</a></span></code>, and semi-smooth <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESVINEWTONSSLS.html">SNESVINEWTONSSLS</a></span></code> solvers.</p>
<p>The
option <code class="docutils notranslate"><span class="pre">-snes_vi_monitor</span></code> turns on extra monitoring of the active set
associated with the bounds and <code class="docutils notranslate"><span class="pre">-snes_vi_type</span></code> allows selecting from
several VI solvers, the default is preferred.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLineSearchSetPreCheck.html">SNESLineSearchSetPreCheck</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESLineSearchSetPostCheck.html">SNESLineSearchSetPostCheck</a>()</span></code> can also be used to control properties
of the steps selected by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>.</p>
</section>
<section id="nonlinear-preconditioning">
<span id="sec-snespc"></span><h2>Nonlinear Preconditioning<a class="headerlink" href="#nonlinear-preconditioning" title="Link to this heading">#</a></h2>
<p>The mathematical framework of nonlinear preconditioning is explained in detail in <span id="id9">[<a class="reference internal" href="../manualpages/SNESFAS/SNESFAS.html#id849" title="Peter R. Brune, Matthew G. Knepley, Barry F. Smith, and Xuemin Tu. Composing scalable nonlinear algebraic solvers. SIAM Review, 57(4):535–565, 2015. http://www.mcs.anl.gov/papers/P2010-0112.pdf. URL: http://www.mcs.anl.gov/papers/P2010-0112.pdf, doi:10.1137/130936725.">BKST15</a>]</span>.
Nonlinear preconditioning in PETSc involves the use of an inner <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>
instance to define the step for an outer <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> instance. The inner
instance may be extracted using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESGetNPC.html">SNESGetNPC</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="n">npc</span><span class="p">);</span>
</pre></div>
</div>
<p>and passed run-time options using the <code class="docutils notranslate"><span class="pre">-npc_</span></code> prefix. Nonlinear
preconditioning comes in two flavors: left and right. The side may be
changed using <code class="docutils notranslate"><span class="pre">-snes_npc_side</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetNPCSide.html">SNESSetNPCSide</a>()</span></code>. Left nonlinear
preconditioning redefines the nonlinear function as the action of the
nonlinear preconditioner <span class="math">\(\mathbf{M}\)</span>;</p>
<div class="math">
\[
\mathbf{F}_{M}(x) = \mathbf{M}(\mathbf{x},\mathbf{b}) - \mathbf{x}.
\]</div>
<p>Right nonlinear preconditioning redefines the nonlinear function as the
function on the action of the nonlinear preconditioner;</p>
<div class="math">
\[
\mathbf{F}(\mathbf{M}(\mathbf{x},\mathbf{b})) = \mathbf{b},
\]</div>
<p>which can be interpreted as putting the preconditioner into “striking
distance” of the solution by outer acceleration.</p>
<p>In addition, basic patterns of solver composition are available with the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESType.html">SNESType</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESCOMPOSITE.html">SNESCOMPOSITE</a></span></code>. This allows for two or more <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>
instances to be combined additively or multiplicatively. By command
line, a set of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> types may be given by comma separated list
argument to <code class="docutils notranslate"><span class="pre">-snes_composite_sneses</span></code>. There are additive
(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESCompositeType.html">SNES_COMPOSITE_ADDITIVE</a></span></code>), additive with optimal damping
(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESCompositeType.html">SNES_COMPOSITE_ADDITIVEOPTIMAL</a></span></code>), and multiplicative
(<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESCompositeType.html">SNES_COMPOSITE_MULTIPLICATIVE</a></span></code>) variants which may be set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESCompositeSetType.html">SNESCompositeSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESCompositeType.html">SNESCompositeType</a></span><span class="p">);</span>
</pre></div>
</div>
<p>New subsolvers may be added to the composite solver with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESCompositeAddSNES.html">SNESCompositeAddSNES</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/SNES/SNESType.html">SNESType</a></span><span class="p">);</span>
</pre></div>
</div>
<p>and accessed with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/SNES/SNESCompositeGetSNES.html">SNESCompositeGetSNES</a></span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</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/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<div class="docutils container" id="id1">
<div role="list" class="citation-list">
<div class="citation" id="id1268" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>BS90<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id6">1</a>,<a role="doc-backlink" href="#id7">2</a>)</span>
<p>Peter N. Brown and Youcef Saad. Hybrid Krylov methods for nonlinear systems of equations. <em>SIAM J. Sci. Stat. Comput.</em>, 11:450–481, 1990.</p>
</div>
<div class="citation" id="id848" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id9">BKST15</a><span class="fn-bracket">]</span></span>
<p>Peter R. Brune, Matthew G. Knepley, Barry F. Smith, and Xuemin Tu. Composing scalable nonlinear algebraic solvers. <em>SIAM Review</em>, 57(4):535–565, 2015. <a class="reference external" href="http://www.mcs.anl.gov/papers/P2010-0112.pdf">http://www.mcs.anl.gov/papers/P2010-0112.pdf</a>. URL: <a class="reference external" href="http://www.mcs.anl.gov/papers/P2010-0112.pdf">http://www.mcs.anl.gov/papers/P2010-0112.pdf</a>, <a class="reference external" href="https://doi.org/10.1137/130936725">doi:10.1137/130936725</a>.</p>
</div>
<div class="citation" id="id1299" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id5">EW96</a><span class="fn-bracket">]</span></span>
<p>S. C. Eisenstat and H. F. Walker. Choosing the forcing terms in an inexact Newton method. <em>SIAM J. Scientific Computing</em>, 17:16–32, 1996.</p>
</div>
<div class="citation" id="id1263" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">JP93</a><span class="fn-bracket">]</span></span>
<p>Mark T. Jones and Paul E. Plassmann. A parallel graph coloring heuristic. <em>SIAM J. Sci. Comput.</em>, 14(3):654–669, 1993.</p>
</div>
<div class="citation" id="id3947" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">LPP+11</a><span class="fn-bracket">]</span></span>
<p>Sofie E. Leon, Glaucio H. Paulino, Anderson Pereira, Ivan F. M. Menezes, and Eduardo N. Lages. A unified library of nonlinear solution schemes. <em>Applied Mechanics Reviews</em>, 64(4):040803, July 2011. <a class="reference external" href="https://doi.org/10.1115/1.4006992">doi:10.1115/1.4006992</a>.</p>
</div>
<div class="citation" id="id2283" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>MoreSGH84<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id2">1</a>,<a role="doc-backlink" href="#id1">2</a>,<a role="doc-backlink" href="#id2">3</a>,<a role="doc-backlink" href="#id3">4</a>)</span>
<p>Jorge J. Moré, Danny C. Sorenson, Burton S. Garbow, and Kenneth E. Hillstrom. The MINPACK project. In Wayne R. Cowell, editor, <em>Sources and Development of Mathematical Software</em>, 88–111. 1984.</p>
</div>
<div class="citation" id="id1219" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">PW98</a><span class="fn-bracket">]</span></span>
<p>M. Pernice and H. F. Walker. NITSOL: a Newton iterative solver for nonlinear systems. <em>SIAM J. Sci. Stat. Comput.</em>, 19:302–318, 1998.</p>
</div>
<div class="citation" id="id3946" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">RCorreaC08</a><span class="fn-bracket">]</span></span>
<p>Manuel Ritto-Corrêa and Dinar Camotim. On the arc-length and other quadratic control methods: established, less known and new implementation procedures. <em>Computers &amp; Structures</em>, 86(11):1353–1368, June 2008. <a class="reference external" href="https://doi.org/10.1016/j.compstruc.2007.08.003">doi:10.1016/j.compstruc.2007.08.003</a>.</p>
</div>
<div class="citation" id="id2288" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">DennisJrS83</a><span class="fn-bracket">]</span></span>
<p>J. E. Dennis Jr. and Robert B. Schnabel. <em>Numerical Methods for Unconstrained Optimization and Nonlinear Equations</em>. Prentice-Hall, Inc., Englewood Cliffs, NJ, 1983.</p>
</div>
</div>
</div>
</section>
</section>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="ksp.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">KSP: Linear System Solvers</p>
      </div>
    </a>
    <a class="right-next"
       href="ts.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">TS: Scalable ODE and DAE 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="#basic-snes-usage">Basic SNES Usage</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nonlinear-function-evaluation">Nonlinear Function Evaluation</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#jacobian-evaluation">Jacobian Evaluation</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#the-nonlinear-solvers">The Nonlinear Solvers</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#line-search-newton">Line Search Newton</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#trust-region-methods">Trust Region Methods</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#newton-with-arc-length-continuation">Newton with Arc Length Continuation</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nonlinear-krylov-methods">Nonlinear Krylov Methods</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#the-full-approximation-scheme">The Full Approximation Scheme</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#nonlinear-additive-schwarz">Nonlinear Additive Schwarz</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#general-options">General Options</a><ul class="nav section-nav flex-column">
<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="#checking-accuracy-of-derivatives">Checking Accuracy of Derivatives</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#inexact-newton-like-methods">Inexact Newton-like Methods</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#matrix-free-methods">Matrix-Free Methods</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#finite-difference-jacobian-approximations">Finite Difference Jacobian Approximations</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#variational-inequalities">Variational Inequalities</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#nonlinear-preconditioning">Nonlinear Preconditioning</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/snes.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/snes.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>