File: other.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 (2100 lines) | stat: -rw-r--r-- 205,541 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>Other PETSc Features &#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/other';</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="Advanced Features of Matrices and Solvers" href="advanced.html" />
    <link rel="prev" title="The Use of BLAS and LAPACK in PETSc and external libraries" href="blas-lapack.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 has-children"><a class="reference internal" href="programming.html">The Solvers in PETSc/TAO</a><input 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>
<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"><a class="reference internal" href="snes.html">SNES: Nonlinear Solvers</a></li>
<li class="toctree-l3"><a class="reference internal" href="ts.html">TS: Scalable ODE and DAE Solvers</a></li>

<li class="toctree-l3"><a class="reference internal" href="tao.html">TAO: Optimization Solvers</a></li>
</ul>
</li>
<li class="toctree-l2 has-children"><a class="reference internal" href="dm.html">DM: Interfacing Between Solvers and Models/Discretizations</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-4"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="dmbase.html">DM Basics</a></li>
<li class="toctree-l3"><a class="reference internal" href="section.html">PetscSection: Connecting Grids to Data</a></li>
<li class="toctree-l3"><a class="reference internal" href="dmplex.html">DMPlex: Unstructured Grids</a></li>
<li class="toctree-l3"><a class="reference internal" href="dmstag.html">DMSTAG: Staggered, Structured Grid</a></li>
<li class="toctree-l3"><a class="reference internal" href="dmnetwork.html">Networks</a></li>
<li class="toctree-l3"><a class="reference internal" href="dt.html">PetscDT: Discretization Technology in PETSc</a></li>
<li class="toctree-l3"><a class="reference internal" href="fe.html">PetscFE: Finite Element Infrastructure in PETSc</a></li>
</ul>
</li>
<li class="toctree-l2 current active has-children"><a class="reference internal" href="additional.html">Additional Information</a><input checked="" 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 class="current">
<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 current active"><a class="current reference internal" href="#">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="additional.html" class="nav-link">Additional Information</a></li>
    
    <li class="breadcrumb-item active" aria-current="page">Other PETSc Features</li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="other-petsc-features">
<h1>Other PETSc Features<a class="headerlink" href="#other-petsc-features" title="Link to this heading">#</a></h1>
<section id="petsc-on-a-process-subset">
<h2>PETSc on a process subset<a class="headerlink" href="#petsc-on-a-process-subset" title="Link to this heading">#</a></h2>
<p>Users who wish to employ PETSc on only a subset of MPI processes
within a larger parallel job, or who wish to use a “manager” process to
coordinate the work of “worker” PETSc processes, should specify an
alternative communicator for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span></code> by directly setting
its value, for example to use an existing MPI communicator <code class="docutils notranslate"><span class="pre">comm</span></code>,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_WORLD.html">PETSC_COMM_WORLD</a></span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">comm</span><span class="p">;</span><span class="w"> </span><span class="cm">/* To use a previously-defined <a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a> */</span>
</pre></div>
</div>
<p><em>before</em> calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code>, but, obviously, after calling
<code class="docutils notranslate"><span class="pre"><a href="http://www.mpich.org/static/docs/latest/www3/MPI_Init.html#MPI_Init">MPI_Init</a>()</span></code>.</p>
</section>
<section id="runtime-options">
<span id="sec-options"></span><h2>Runtime Options<a class="headerlink" href="#runtime-options" title="Link to this heading">#</a></h2>
<p>Allowing the user to modify parameters and options easily at runtime is
very desirable for many applications. PETSc provides a simple mechanism
to enable such customization. To print a list of available options for a
given program, simply specify the option <code class="docutils notranslate"><span class="pre">-help</span></code> at
runtime, e.g.,</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mpiexec<span class="w"> </span>-n<span class="w"> </span><span class="m">1</span><span class="w"> </span>./ex1<span class="w"> </span>-help
</pre></div>
</div>
<p>Note that all runtime options correspond to particular PETSc routines
that can be explicitly called from within a program to set compile-time
defaults. For many applications it is natural to use a combination of
compile-time and runtime choices. For example, when solving a linear
system, one could explicitly specify use of the Krylov subspace
solver BiCGStab by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/KSP/KSPSetType.html">KSPSetType</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/KSP/KSPBCGS.html">KSPBCGS</a></span><span class="p">);</span>
</pre></div>
</div>
<p>One could then override this choice at runtime with the option</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">ksp_type</span><span class="w"> </span><span class="n">tfqmr</span>
</pre></div>
</div>
<p>to select the Transpose-Free QMR algorithm. (See
<a class="reference internal" href="ksp.html#ch-ksp"><span class="std std-ref">KSP: Linear System Solvers</span></a> for details.)</p>
<p>The remainder of this section discusses details of runtime options.</p>
<section id="the-options-database">
<span id="the-options-database-1"></span><h3>The Options Database<a class="headerlink" href="#the-options-database" title="Link to this heading">#</a></h3>
<p>Each PETSc process maintains a database of option names and values
(stored as text strings). This database is generated with the command
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code>, which is listed below in its C/C++ and Fortran
variants, respectively:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="o">*</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">args</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">help</span><span class="p">);</span><span class="w"> </span><span class="c1">// C</span>
</pre></div>
</div>
<div class="highlight-fortran notranslate"><div class="highlight"><pre><span></span><span class="k">call </span><span class="n"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a></span><span class="p">(</span><span class="kt">integer </span><span class="n">ierr</span><span class="p">)</span><span class="w"> </span><span class="c">! Fortran</span>
</pre></div>
</div>
<p>The arguments <code class="docutils notranslate"><span class="pre">argc</span></code> and <code class="docutils notranslate"><span class="pre">args</span></code> (in the C/C++ version only) are the
addresses of the usual command line arguments, while the <code class="docutils notranslate"><span class="pre">file</span></code> is a name
of an optional file that can contain additional options. By default this file is
called <code class="docutils notranslate"><span class="pre">.petscrc</span></code> in the user’s home directory. The user can also
specify options via the environmental variable <code class="docutils notranslate"><span class="pre">PETSC_OPTIONS</span></code>. The
options are processed in the following order:</p>
<ol class="arabic simple">
<li><p>file</p></li>
<li><p>environmental variable</p></li>
<li><p>command line</p></li>
</ol>
<p>Thus, the command line options supersede the environmental variable
options, which in turn supersede the options file.</p>
<p>The file format for specifying options is</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-optionname possible_value
-anotheroptionname possible_value
...
</pre></div>
</div>
<p>All of the option names must begin with a dash (-) and have no
intervening spaces. Note that the option values cannot have intervening
spaces either, and tab characters cannot be used between the option
names and values. For
uniformity throughout PETSc, we employ the format
<code class="docutils notranslate"><span class="pre">-[prefix_]package_option</span></code> (for instance, <code class="docutils notranslate"><span class="pre">-ksp_type</span></code>,
<code class="docutils notranslate"><span class="pre">-mat_view</span> <span class="pre">::info</span></code>, or <code class="docutils notranslate"><span class="pre">-mg_levels_ksp_type</span></code>).</p>
<p>Users can specify an alias for any option name (to avoid typing the
sometimes lengthy default name) by adding an alias to the <code class="docutils notranslate"><span class="pre">.petscrc</span></code>
file in the format</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>alias -newname -oldname
</pre></div>
</div>
<p>For example,</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>alias -kspt -ksp_type
alias -sd -start_in_debugger
</pre></div>
</div>
<p>Comments can be placed in the <code class="docutils notranslate"><span class="pre">.petscrc</span></code> file by using <code class="docutils notranslate"><span class="pre">#</span></code> in the
first column of a line.</p>
</section>
<section id="options-prefixes">
<h3>Options Prefixes<a class="headerlink" href="#options-prefixes" title="Link to this heading">#</a></h3>
<p>Options prefixes allow specific objects to be controlled from the
options database. For instance, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code> gives prefixes to its nested
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> objects; one may control the coarse grid solver by adding the
<code class="docutils notranslate"><span class="pre">mg_coarse</span></code> prefix, for example <code class="docutils notranslate"><span class="pre">-mg_coarse_ksp_type</span> <span class="pre">preonly</span></code>. One
may also use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPSetOptionsPrefix.html">KSPSetOptionsPrefix</a>()</span></code>,<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMSetOptionsPrefix.html">DMSetOptionsPrefix</a>()</span></code> ,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESSetOptionsPrefix.html">SNESSetOptionsPrefix</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetOptionsPrefix.html">TSSetOptionsPrefix</a>()</span></code>, and similar
functions to assign custom prefixes, useful for applications with
multiple or nested solvers.</p>
</section>
<section id="adding-options-from-a-file">
<h3>Adding options from a file<a class="headerlink" href="#adding-options-from-a-file" title="Link to this heading">#</a></h3>
<p>PETSc can load additional options from a file using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsInsertFile.html">PetscOptionsInsertFile</a>()</span></code>,
which can also be used from the command line, e.g. <code class="docutils notranslate"><span class="pre">-options_file</span> <span class="pre">my_options.opts</span></code>.</p>
<p>One can also use YAML files with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsInsertFileYAML.html">PetscOptionsInsertFileYAML</a>()</span></code>.
For example, the following file:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">$$</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ignored</span>
<span class="nt">$$tail</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ignored</span>

<span class="nt">$$ans</span><span class="p">:</span><span class="w"> </span><span class="nl">&amp;ans</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">42</span>
<span class="nt">$$eu</span><span class="p">:</span><span class="w">  </span><span class="nl">&amp;eu</span><span class="w">  </span><span class="l l-Scalar l-Scalar-Plain">2.72</span>
<span class="nt">$$pi</span><span class="p">:</span><span class="w">  </span><span class="nl">&amp;pi</span><span class="w">  </span><span class="l l-Scalar l-Scalar-Plain">3.14</span>

<span class="nt">opt</span><span class="p">:</span>
<span class="w">  </span><span class="nt">bool</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w">  </span><span class="nt">int</span><span class="p">:</span><span class="w"> </span><span class="nv">*ans</span>
<span class="w">  </span><span class="nt">real</span><span class="p">:</span><span class="w"> </span><span class="nv">*pi</span>
<span class="w">  </span><span class="nt">imag</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2.72i</span>
<span class="w">  </span><span class="nt">cmplx</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">-3.14+2.72i</span>
<span class="w">  </span><span class="nt">str</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">petsc</span>

<span class="nt">$$1</span><span class="p">:</span><span class="w"> </span><span class="nl">&amp;seq-bool</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">true</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">false</span><span class="p p-Indicator">]</span>
<span class="nt">$$2</span><span class="p">:</span><span class="w"> </span><span class="nl">&amp;seq-int</span><span class="w">  </span><span class="p p-Indicator">[</span><span class="nv">123</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">456</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">789</span><span class="p p-Indicator">]</span>
<span class="nt">$$3</span><span class="p">:</span><span class="w"> </span><span class="nl">&amp;seq-real</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="nv">*pi</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">*eu</span><span class="p p-Indicator">]</span>
<span class="nt">$$4</span><span class="p">:</span><span class="w"> </span><span class="nl">&amp;seq-str</span><span class="w">  </span><span class="p p-Indicator">[</span><span class="nv">abc</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">ijk</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="nv">fgh</span><span class="p p-Indicator">]</span>

<span class="nt">seq1</span><span class="p">:</span><span class="w"> </span><span class="p p-Indicator">{</span>
<span class="nt">  bool</span><span class="p">:</span><span class="w"> </span><span class="nv">*seq-bool</span><span class="p p-Indicator">,</span>
<span class="nt">  int</span><span class="p">:</span><span class="w">  </span><span class="nv">*seq-int</span><span class="p p-Indicator">,</span>
<span class="nt">  real</span><span class="p">:</span><span class="w"> </span><span class="nv">*seq-real</span><span class="p p-Indicator">,</span>
<span class="nt">  str</span><span class="p">:</span><span class="w">  </span><span class="nv">*seq-str</span><span class="p p-Indicator">,</span>
<span class="p p-Indicator">}</span>

<span class="nt">seq2</span><span class="p">:</span>
<span class="w">  </span><span class="nt">bool</span><span class="p">:</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
<span class="w">  </span><span class="nt">int</span><span class="p">:</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">123</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">456</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">789</span>
<span class="w">  </span><span class="nt">real</span><span class="p">:</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nv">*pi</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nv">*eu</span>
<span class="w">  </span><span class="nt">str</span><span class="p">:</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">rst</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">uvw</span>
<span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">xyz</span>

<span class="nt">map</span><span class="p">:</span>
<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">key0</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">key1</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1</span>
<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">key2</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span>
<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">$$</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ignored</span>
<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">$$tail</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ignored</span>
</pre></div>
</div>
<p>corresponds to the following PETSc options:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-map key0,key1,key2 # (source: file)
-map_key0 0 # (source: file)
-map_key1 1 # (source: file)
-map_key2 2 # (source: file)
-opt_bool true # (source: file)
-opt_cmplx -3.14+2.72i # (source: file)
-opt_imag 2.72i # (source: file)
-opt_int 42 # (source: file)
-opt_real 3.14 # (source: file)
-opt_str petsc # (source: file)
-seq1_bool true,false # (source: file)
-seq1_int 123,456,789 # (source: file)
-seq1_real 3.14,2.72 # (source: file)
-seq1_str abc,ijk,fgh # (source: file)
-seq2_bool true,false # (source: file)
-seq2_int 123,456,789 # (source: file)
-seq2_real 3.14,2.72 # (source: file)
-seq2_str rst,uvw,xyz # (source: file)
</pre></div>
</div>
<p>With <code class="docutils notranslate"><span class="pre">-options_file</span></code>, PETSc will parse the file as YAML if it ends in a standard
YAML or JSON <a class="footnote-reference brackets" href="#json" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> extension or if one uses a <code class="docutils notranslate"><span class="pre">:yaml</span></code> postfix,
e.g. <code class="docutils notranslate"><span class="pre">-options_file</span> <span class="pre">my_options.yaml</span></code> or <code class="docutils notranslate"><span class="pre">-options_file</span> <span class="pre">my_options.txt:yaml</span></code></p>
<p>PETSc will also check the first line of the options file itself and
parse the file as YAML if it matches certain criteria, for example.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">%YAML</span><span class="w"> </span><span class="m">1.2</span>
<span class="nn">---</span>
<span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">value</span>
</pre></div>
</div>
<p>and</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span>
<span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">value</span>
</pre></div>
</div>
<p>both correspond to options</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-name value # (source: file)
</pre></div>
</div>
</section>
<section id="user-defined-petscoptions">
<h3>User-Defined PetscOptions<a class="headerlink" href="#user-defined-petscoptions" title="Link to this heading">#</a></h3>
<p>Any subroutine in a PETSc program can add entries to the database with
the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscOptionsSetValue.html">PetscOptionsSetValue</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">name</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">value</span><span class="p">);</span>
</pre></div>
</div>
<p>though this is rarely done. To locate options in the database, one
should use the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscOptionsHasName.html">PetscOptionsHasName</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscOptionsGetInt.html">PetscOptionsGetInt</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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">value</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">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscOptionsGetReal.html">PetscOptionsGetReal</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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="o">*</span><span class="n">value</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">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscOptionsGetString.html">PetscOptionsGetString</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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">value</span><span class="p">,</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">maxlen</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">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscOptionsGetStringArray.html">PetscOptionsGetStringArray</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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">values</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">nmax</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">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscOptionsGetIntArray.html">PetscOptionsGetIntArray</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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">value</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">nmax</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">flg</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscOptionsGetRealArray.html">PetscOptionsGetRealArray</a></span><span class="p">(</span><span class="n">PetscOptions</span><span class="w"> </span><span class="n">options</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">pre</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">name</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="o">*</span><span class="n">value</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">nmax</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">flg</span><span class="p">);</span>
</pre></div>
</div>
<p>All of these routines set <code class="docutils notranslate"><span class="pre">flg=<a href="../manualpages/Sys/PETSC_TRUE.html">PETSC_TRUE</a></span></code> if the corresponding option
was found, <code class="docutils notranslate"><span class="pre">flg=<a href="../manualpages/Sys/PETSC_FALSE.html">PETSC_FALSE</a></span></code> if it was not found. The optional
argument <code class="docutils notranslate"><span class="pre">pre</span></code> indicates that the true name of the option is the given
name (with the dash “-” removed) prepended by the prefix <code class="docutils notranslate"><span class="pre">pre</span></code>.
Usually <code class="docutils notranslate"><span class="pre">pre</span></code> should be set to <code class="docutils notranslate"><span class="pre">NULL</span></code> (or <code class="docutils notranslate"><span class="pre">PETSC_NULL_CHARACTER</span></code>
for Fortran); its purpose is to allow someone to rename all the options
in a package without knowing the names of the individual options. For
example, when using block Jacobi preconditioning, 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>
methods used on the individual blocks can be controlled via the options
<code class="docutils notranslate"><span class="pre">-sub_ksp_type</span></code> and <code class="docutils notranslate"><span class="pre">-sub_pc_type</span></code>.</p>
</section>
<section id="keeping-track-of-options">
<h3>Keeping Track of Options<a class="headerlink" href="#keeping-track-of-options" title="Link to this heading">#</a></h3>
<p>One useful means of keeping track of user-specified runtime options is
use of <code class="docutils notranslate"><span class="pre">-options_view</span></code>, which prints to <code class="docutils notranslate"><span class="pre">stdout</span></code> during
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a>()</span></code> a table of all runtime options that the user has
specified. A related option is <code class="docutils notranslate"><span class="pre">-options_left</span></code>, which prints the
options table and indicates any options that have <em>not</em> been requested
upon a call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFinalize.html">PetscFinalize</a>()</span></code>. This feature is useful to check
whether an option has been activated for a particular PETSc object (such
as a solver or matrix format), or whether an option name may have been
accidentally misspelled.</p>
<p>The option <code class="docutils notranslate"><span class="pre">-options_monitor</span></code> <code class="docutils notranslate"><span class="pre">&lt;viewer&gt;</span></code> turns on the default monitoring of options.
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsMonitorSet.html">PetscOptionsMonitorSet</a>()</span></code> can be used to provide custom monitors.
The option <code class="docutils notranslate"><span class="pre">-options_monitor_cancel</span></code> prevents any monitoring by monitors set with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscOptionsMonitorSet.html">PetscOptionsMonitorSet</a>()</span></code> (but not that set with <code class="docutils notranslate"><span class="pre">-options_monitor</span></code>).</p>
</section>
</section>
<section id="viewers-looking-at-petsc-objects">
<span id="sec-viewers"></span><h2>Viewers: Looking at PETSc Objects<a class="headerlink" href="#viewers-looking-at-petsc-objects" title="Link to this heading">#</a></h2>
<p>PETSc employs a consistent scheme for examining, printing, and saving
objects through commands of the form</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">XXXView</span><span class="p">(</span><span class="n">XXX</span><span class="w"> </span><span class="n">obj</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>
</pre></div>
</div>
<p>Here <code class="docutils notranslate"><span class="pre">obj</span></code> is a PETSc object of type <code class="docutils notranslate"><span class="pre">XXX</span></code>, where <code class="docutils notranslate"><span class="pre">XXX</span></code> is
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>, etc. There are several predefined viewers.</p>
<ul class="simple">
<li><p>Passing in a zero (<code class="docutils notranslate"><span class="pre">0</span></code>) for the viewer causes the object to be
printed to the screen; this is useful when viewing an object in a
debugger but should be avoided in source code.</p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_SELF.html">PETSC_VIEWER_STDOUT_SELF</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_WORLD.html">PETSC_VIEWER_STDOUT_WORLD</a></span></code> causes
the object to be printed to the screen.</p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_DRAW_SELF.html">PETSC_VIEWER_DRAW_SELF</a></span></code> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_DRAW_WORLD.html">PETSC_VIEWER_DRAW_WORLD</a></span></code> causes the
object to be drawn in a default X window.</p></li>
<li><p>Passing in a viewer obtained by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerDrawOpen.html">PetscViewerDrawOpen</a>()</span></code> causes the
object to be displayed graphically. See
<a class="reference internal" href="#sec-graphics"><span class="std std-ref">Graphics</span></a> for more on PETSc’s graphics support.</p></li>
<li><p>To save an object to a file in ASCII format, the user creates the
viewer object with the command
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerASCIIOpen.html">PetscViewerASCIIOpen</a>(<a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span> <span class="pre">comm,</span> <span class="pre">char*</span> <span class="pre">file,</span> <span class="pre"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span> <span class="pre">*viewer)</span></code>.
This object is analogous to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_SELF.html">PETSC_VIEWER_STDOUT_SELF</a></span></code> (for a
communicator of <code class="docutils notranslate"><span class="pre">MPI_COMM_SELF</span></code>) and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_WORLD.html">PETSC_VIEWER_STDOUT_WORLD</a></span></code>
(for a parallel communicator).</p></li>
<li><p>To save an object to a file in binary format, the user creates the
viewer object with the command
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinaryOpen.html">PetscViewerBinaryOpen</a>(<a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span> <span class="pre">comm,</span> <span class="pre">char*</span> <span class="pre">file,</span> <span class="pre">PetscViewerBinaryType</span> <span class="pre">type,</span> <span class="pre"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span> <span class="pre">*viewer)</span></code>.
Details of binary I/O are discussed below.</p></li>
<li><p>Vector and matrix objects can be passed to a running MATLAB process
with a viewer created by
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerSocketOpen.html">PetscViewerSocketOpen</a>(<a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span> <span class="pre">comm,</span> <span class="pre">char</span> <span class="pre">*machine,</span> <span class="pre">int</span> <span class="pre">port,</span> <span class="pre"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span> <span class="pre">*viewer)</span></code>.
See <a class="reference internal" href="matlab.html#sec-matlabsocket"><span class="std std-ref">Sending Data to an Interactive MATLAB Session</span></a>.</p></li>
</ul>
<p>The user can control the format of ASCII printed objects with viewers
created by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerASCIIOpen.html">PetscViewerASCIIOpen</a>()</span></code> by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Viewer/PetscViewerPushFormat.html">PetscViewerPushFormat</a></span><span class="p">(</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="w"> </span><span class="n"><a href="../manualpages/Viewer/PetscViewerFormat.html">PetscViewerFormat</a></span><span class="w"> </span><span class="n">format</span><span class="p">);</span>
</pre></div>
</div>
<p>Formats include <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFormat.html">PETSC_VIEWER_DEFAULT</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFormat.html">PETSC_VIEWER_ASCII_MATLAB</a></span></code>,
and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFormat.html">PETSC_VIEWER_ASCII_IMPL</a></span></code>. The implementation-specific format,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFormat.html">PETSC_VIEWER_ASCII_IMPL</a></span></code>, displays the object in the most natural way
for a particular implementation.</p>
<p>The routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Viewer/PetscViewerPushFormat.html">PetscViewerPushFormat</a></span><span class="p">(</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="w"> </span><span class="n"><a href="../manualpages/Viewer/PetscViewerFormat.html">PetscViewerFormat</a></span><span class="w"> </span><span class="n">format</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Viewer/PetscViewerPopFormat.html">PetscViewerPopFormat</a></span><span class="p">(</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>
</pre></div>
</div>
<p>allow one to temporarily change the format of a viewer.</p>
<p>As discussed above, one can output PETSc objects in binary format by
first opening a binary viewer with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerBinaryOpen.html">PetscViewerBinaryOpen</a>()</span></code> and then
using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatView.html">MatView</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecView.html">VecView</a>()</span></code>, etc. The corresponding routines for
input of a binary object have the form <code class="docutils notranslate"><span class="pre">XXXLoad()</span></code>. In particular,
matrix and vector binary input is handled by the following routines:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Mat/MatLoad.html">MatLoad</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">newmat</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="n"><a href="../manualpages/Vec/VecLoad.html">VecLoad</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">newvec</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>
</pre></div>
</div>
<p>These routines generate parallel matrices and vectors if the viewer’s
communicator has more than one process. The particular matrix and vector
formats are determined from the options database; see the manual pages
for details.</p>
<p>One can provide additional information about matrix data for matrices
stored on disk by providing an optional file <code class="docutils notranslate"><span class="pre">matrixfilename.info</span></code>,
where <code class="docutils notranslate"><span class="pre">matrixfilename</span></code> is the name of the file containing the matrix.
The format of the optional file is the same as the <code class="docutils notranslate"><span class="pre">.petscrc</span></code> file and
can (currently) contain the following:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-matload_block_size &lt;bs&gt;
</pre></div>
</div>
<p>The block size indicates the size of blocks to use if the matrix is read
into a block oriented data structure (for example, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATMPIBAIJ.html">MATMPIBAIJ</a></span></code>). The
diagonal information <code class="docutils notranslate"><span class="pre">s1,s2,s3,...</span></code> indicates which (block) diagonals
in the matrix have nonzero values. The info file is automatically created
when <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecView.html">VecView</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatView.html">MatView</a>()</span></code> is used with a binary viewer; hence if you
save a matrix with a given block size with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatView.html">MatView</a>()</span></code>, then a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatLoad.html">MatLoad</a>()</span></code>
on that file will automatically use the saved block size.</p>
<section id="viewing-from-options">
<span id="sec-viewfromoptions"></span><h3>Viewing From Options<a class="headerlink" href="#viewing-from-options" title="Link to this heading">#</a></h3>
<p>Command-line options provide a particularly convenient way to view PETSc
objects. All options of the form <code class="docutils notranslate"><span class="pre">-xxx_view</span></code> accept
colon(<code class="docutils notranslate"><span class="pre">:</span></code>)-separated compound arguments which specify a viewer type,
format, and/or destination (e.g. file name or socket) if appropriate.
For example, to quickly export a binary file containing a matrix, one
may use <code class="docutils notranslate"><span class="pre">-mat_view</span> <span class="pre">binary:matrix.out</span></code>, or to output to a
MATLAB-compatible ASCII file, one may use
<code class="docutils notranslate"><span class="pre">-mat_view</span> <span class="pre">ascii:matrix.m:ascii_matlab</span></code>. See the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscOptionsCreateViewer.html">PetscOptionsCreateViewer</a>()</span></code> man page for full details, as well as the
<code class="docutils notranslate"><span class="pre">XXXViewFromOptions()</span></code> man pages (for instance,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawSetFromOptions.html">PetscDrawSetFromOptions</a>()</span></code>) for many other convenient command-line
options.</p>
</section>
<section id="using-viewers-to-check-load-imbalance">
<h3>Using Viewers to Check Load Imbalance<a class="headerlink" href="#using-viewers-to-check-load-imbalance" title="Link to this heading">#</a></h3>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span></code> format <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFormat.html">PETSC_VIEWER_LOAD_BALANCE</a></span></code> will cause certain
objects to display simple measures of their imbalance. For example</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-n 4 ./ex32 -ksp_view_mat ::load_balance
</pre></div>
</div>
<p>will display</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Nonzeros: Min 162  avg 168  max 174
</pre></div>
</div>
<p>indicating that one process has 162 nonzero entries in the matrix, the
average number of nonzeros per process is 168 and the maximum number of
nonzeros is 174. Similar for vectors one can see the load balancing
with, for example,</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-n 4 ./ex32 -ksp_view_rhs ::load_balance
</pre></div>
</div>
<p>The measurements of load balancing can also be done within the program
with calls to the appropriate object viewer with the viewer format
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerFormat.html">PETSC_VIEWER_LOAD_BALANCE</a></span></code>.</p>
</section>
</section>
<section id="using-saws-with-petsc">
<span id="sec-saws"></span><h2>Using SAWs with PETSc<a class="headerlink" href="#using-saws-with-petsc" title="Link to this heading">#</a></h2>
<p>The Scientific Application Web server, SAWs <a class="footnote-reference brackets" href="#saws" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>, allows one to monitor
running PETSc applications from a browser. To use SAWs you must <code class="docutils notranslate"><span class="pre">configure</span></code> PETSc with
the option <code class="docutils notranslate"><span class="pre">--download-saws</span></code>. Options to use SAWs include</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-saws_options</span></code> - allows setting values in the PETSc options
database via the browser (works only on one process).</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-stack_view</span> <span class="pre">saws</span></code> - allows monitoring the current stack frame that
PETSc is in; refresh to see the new location.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-snes_monitor_saws,</span> <span class="pre">-ksp_monitor_saws</span></code> - monitor the solvers’
iterations from the web browser.</p></li>
</ul>
<p>For each of these you need to point your browser to
<code class="docutils notranslate"><span class="pre">http://hostname:8080</span></code>, for example <code class="docutils notranslate"><span class="pre">http://localhost:8080</span></code>. Options
that control behavior of SAWs include</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-saws_log</span> <span class="pre">filename</span></code> - log all SAWs actions in a file.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-saws_https</span> <span class="pre">certfile</span></code> - use HTTPS instead of HTTP with a
certificate.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-saws_port_auto_select</span></code> - have SAWs pick a port number instead of
using 8080.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-saws_port</span> <span class="pre">port</span></code> - use <code class="docutils notranslate"><span class="pre">port</span></code> instead of 8080.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-saws_root</span> <span class="pre">rootdirectory</span></code> - local directory to which the SAWs
browser will have read access.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-saws_local</span></code> - use the local file system to obtain the SAWS
javascript files (they much be in <code class="docutils notranslate"><span class="pre">rootdirectory/js</span></code>).</p></li>
</ul>
<p>Also see the manual pages for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscSAWsBlock.html">PetscSAWsBlock</a>()</span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectSAWsTakeAccess.html">PetscObjectSAWsTakeAccess</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectSAWsGrantAccess.html">PetscObjectSAWsGrantAccess</a>()</span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectSAWsSetBlock.html">PetscObjectSAWsSetBlock</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscStackSAWsGrantAccess.html">PetscStackSAWsGrantAccess</a>()</span></code>
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscStackSAWsTakeAccess.html">PetscStackSAWsTakeAccess</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPMonitorSAWs.html">KSPMonitorSAWs</a>()</span></code>, and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNESMonitorSAWs.html">SNESMonitorSAWs</a>()</span></code>.</p>
</section>
<section id="debugging">
<span id="sec-debugging"></span><h2>Debugging<a class="headerlink" href="#debugging" title="Link to this heading">#</a></h2>
<p>PETSc programs may be debugged using one of the two options below.</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-start_in_debugger</span></code> <code class="docutils notranslate"><span class="pre">[noxterm,dbx,xxgdb,xdb,xldb,lldb]</span></code>
<code class="docutils notranslate"><span class="pre">[-display</span> <span class="pre">name]</span></code> - start all processes in debugger</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-on_error_attach_debugger</span></code> <code class="docutils notranslate"><span class="pre">[noxterm,dbx,xxgdb,xdb,xldb,lldb]</span></code>
<code class="docutils notranslate"><span class="pre">[-display</span> <span class="pre">name]</span></code> - start debugger only on encountering an error</p></li>
</ul>
<p>Note that, in general, debugging MPI programs cannot be done in the
usual manner of starting the programming in the debugger (because then
it cannot set up the MPI communication and remote processes).</p>
<p>By default on Linux systems the GNU debugger <code class="docutils notranslate"><span class="pre">gdb</span></code> is used, on macOS systems <code class="docutils notranslate"><span class="pre">lldb</span></code> is used</p>
<p>By default, the debugger will be started in a new
xterm (Apple Terminal on macOS), to enable running separate debuggers on each process, unless the
option <code class="docutils notranslate"><span class="pre">noxterm</span></code> is used. In order to handle the MPI startup phase,
the debugger command <code class="docutils notranslate"><span class="pre">cont</span></code> should be used to continue execution of
the program within the debugger. Rerunning the program through the
debugger requires terminating the first job and restarting the
processor(s); the usual <code class="docutils notranslate"><span class="pre">run</span></code> option in the debugger will not
correctly handle the MPI startup and should not be used. Not all
debuggers work on all machines, the user may have to experiment to find
one that works correctly.</p>
<p>You can select a subset of the processes to be debugged (the rest just
run without the debugger) with the option</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-debugger_ranks rank1,rank2,...
</pre></div>
</div>
<p>where you simply list the ranks you want the debugger to run with.</p>
</section>
<section id="error-handling">
<span id="sec-errors"></span><h2>Error Handling<a class="headerlink" href="#error-handling" title="Link to this heading">#</a></h2>
<p>Errors are handled through the routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscError.html">PetscError</a>()</span></code>. This routine
checks a stack of error handlers and calls the one on the top. If the
stack is empty, it selects <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscTraceBackErrorHandler.html">PetscTraceBackErrorHandler</a>()</span></code>, which tries
to print a traceback. A new error handler can be put on the stack with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscPushErrorHandler.html">PetscPushErrorHandler</a></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">HandlerFunction</span><span class="p">)(</span><span class="kt">int</span><span class="w"> </span><span class="n">line</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">dir</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">file</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">message</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">number</span><span class="p">,</span><span class="w"> </span><span class="kt">void</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="n">HandlerContext</span><span class="p">)</span>
</pre></div>
</div>
<p>The arguments to <code class="docutils notranslate"><span class="pre">HandlerFunction()</span></code> are the line number where the
error occurred, the file in which the error was detected, the
corresponding directory, the error message, the error integer, and the
<code class="docutils notranslate"><span class="pre">HandlerContext.</span></code> The routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscPopErrorHandler.html">PetscPopErrorHandler</a></span><span class="p">()</span>
</pre></div>
</div>
<p>removes the last error handler and discards it.</p>
<p>PETSc provides two additional error handlers besides
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscTraceBackErrorHandler.html">PetscTraceBackErrorHandler</a>()</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscAbortErrorHandler.html">PetscAbortErrorHandler</a></span><span class="p">()</span>
<span class="n"><a href="../manualpages/Sys/PetscAttachDebuggerErrorHandler.html">PetscAttachDebuggerErrorHandler</a></span><span class="p">()</span>
</pre></div>
</div>
<p>The function <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscAbortErrorHandler.html">PetscAbortErrorHandler</a>()</span></code> calls abort on encountering an
error, while <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscAttachDebuggerErrorHandler.html">PetscAttachDebuggerErrorHandler</a>()</span></code> attaches a debugger to the
running process if an error is detected. At runtime, these error
handlers can be set with the options <code class="docutils notranslate"><span class="pre">-on_error_abort</span></code> or
<code class="docutils notranslate"><span class="pre">-on_error_attach_debugger</span></code> <code class="docutils notranslate"><span class="pre">[noxterm,</span> <span class="pre">dbx,</span> <span class="pre">xxgdb,</span> <span class="pre">xldb]</span></code>
<code class="docutils notranslate"><span class="pre">[-display</span> <span class="pre">DISPLAY]</span></code>.</p>
<p>All PETSc calls can be traced (useful for determining where a program is
hanging without running in the debugger) with the option</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-log_trace [filename]
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">filename</span></code> is optional. By default the traces are printed to the
screen. This can also be set with the command
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Log/PetscLogTraceBegin.html">PetscLogTraceBegin</a>(FILE*)</span></code>.</p>
<p>It is also possible to trap signals by using the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscPushSignalHandler.html">PetscPushSignalHandler</a></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">Handler</span><span class="p">)(</span><span class="kt">int</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="w"> </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 default handler <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscSignalHandlerDefault.html">PetscSignalHandlerDefault</a>()</span></code> calls
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscError.html">PetscError</a>()</span></code> and then terminates. In general, a signal in PETSc
indicates a catastrophic failure. Any error handler that the user
provides should try to clean up only before exiting. By default all
PETSc programs turn on the default PETSc signal handler in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code>,
this can be prevented with the option <code class="docutils notranslate"><span class="pre">-no_signal_handler</span></code> that can be provided on the command line,
in the ~./petscrc file, or with the call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsSetValue.html">PetscOptionsSetValue</a></span><span class="p">(</span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;-no_signal_handler&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;true&quot;</span><span class="p">));</span>
</pre></div>
</div>
<p>Once the first PETSc signal handler has been pushed it is impossible to go back to
to a signal handler that was set directly by the user with the UNIX signal handler API or by
the loader.</p>
<p>Some Fortran compilers/loaders cause, by default, a traceback of the Fortran call stack when a
segmentation violation occurs to be printed. This is handled by them setting a special signal handler
when the program is started up. This feature is useful for debugging without needing to start up a debugger.
If <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscPushSignalHandler.html">PetscPushSignalHandler</a>()</span></code> has been called this traceback will not occur, hence if the Fortran traceback
is desired one should put</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCallA.html">PetscCallA</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsSetValue.html">PetscOptionsSetValue</a></span><span class="p">(</span><span class="n">PETSC_NULL_OPTIONS</span><span class="p">,</span><span class="s">&quot;-no_signal_handler&quot;</span><span class="p">,</span><span class="s">&quot;true&quot;</span><span class="p">,</span><span class="n">ierr</span><span class="p">))</span>
</pre></div>
</div>
<p><strong>before</strong> the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscInitialize.html">PetscInitialize</a>()</span></code>. This prevents PETSc from defaulting to using a signal handler.</p>
<p>There is a separate signal handler for floating-point exceptions. The
option <code class="docutils notranslate"><span class="pre">-fp_trap</span></code> turns on the floating-point trap at runtime, and the
routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscFPTrapPush.html">PetscFPTrapPush</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscFPTrap.html">PetscFPTrap</a></span><span class="w"> </span><span class="n">flag</span><span class="p">);</span>
</pre></div>
</div>
<p>can be used within a program. A <code class="docutils notranslate"><span class="pre">flag</span></code> of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFPTrap.html">PETSC_FP_TRAP_ON</a></span></code> indicates that
floating-point exceptions should be trapped, while a value of
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFPTrap.html">PETSC_FP_TRAP_OFF</a></span></code> (the default) indicates that they should be
ignored.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscFPTrapPop.html">PetscFPTrapPop</a></span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
</pre></div>
</div>
<p>should be used to revert to the previous handling of floating point exceptions before the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFPTrapPush.html">PetscFPTrapPush</a>()</span></code>.</p>
<p>A small set of macros is used to make the error handling lightweight.
These macros are used throughout the PETSc libraries and can be employed
by the application programmer as well. When an error is first detected,
one should set it by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/SETERRQ.html">SETERRQ</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="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="n">flag</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">message</span><span class="p">);</span>
</pre></div>
</div>
<p>The user should check the return codes for all PETSc routines (and
possibly user-defined routines as well) with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n">PetscRoutine</span><span class="p">(...));</span>
</pre></div>
</div>
<p>Likewise, all memory allocations should be checked with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscMalloc1.html">PetscMalloc1</a></span><span class="p">(</span><span class="n">n</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ptr</span><span class="p">));</span>
</pre></div>
</div>
<p>If this procedure is followed throughout all of the user’s libraries and
codes, any error will by default generate a clean traceback of the
location of the error.</p>
<p>Note that the macro <code class="docutils notranslate"><span class="pre">PETSC_FUNCTION_NAME</span></code> is used to keep track of
routine names during error tracebacks. Users need not worry about this
macro in their application codes; however, users can take advantage of
this feature if desired by setting this macro before each user-defined
routine that may call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/SETERRQ.html">SETERRQ</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a>()</span></code>. A simple example of
usage is given below.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">MyRoutine1</span><span class="p">()</span>
<span class="p">{</span>
<span class="w">    </span><span class="cm">/* Declarations Here */</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">/* code here */</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>
</section>
<section id="numbers">
<span id="sec-complex"></span><h2>Numbers<a class="headerlink" href="#numbers" title="Link to this heading">#</a></h2>
<p>PETSc supports the use of complex numbers in application programs
written in C, C++, and Fortran. To do so, we employ either the C99
<code class="docutils notranslate"><span class="pre">complex</span></code> type or the C++ versions of the PETSc libraries in which the
basic “scalar” datatype, given in PETSc codes by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span></code>, is
defined as <code class="docutils notranslate"><span class="pre">complex</span></code> (or <code class="docutils notranslate"><span class="pre">complex&lt;double&gt;</span></code> for machines using
templated complex class libraries). To work with complex numbers, the
user should run <code class="docutils notranslate"><span class="pre">configure</span></code> with the additional option
<code class="docutils notranslate"><span class="pre">--with-scalar-type=complex</span></code>. The
<a class="reference internal" href="../install/index.html"><span class="doc">installation instructions</span></a>
provide detailed instructions for installing PETSc. You can use
<code class="docutils notranslate"><span class="pre">--with-clanguage=c</span></code> (the default) to use the C99 complex numbers or
<code class="docutils notranslate"><span class="pre">--with-clanguage=c++</span></code> to use the C++ complex type <a class="footnote-reference brackets" href="#cxx-note" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a>.</p>
<p>Recall that each configuration of the PETSc libraries is stored in a different
directory, given by <code class="docutils notranslate"><span class="pre">$PETSC_DIR/$PETSC_ARCH</span></code>
according to the architecture. Thus, the libraries for complex numbers
are maintained separately from those for real numbers. When using any of
the complex numbers versions of PETSc, <em>all</em> vector and matrix elements
are treated as complex, even if their imaginary components are zero. Of
course, one can elect to use only the real parts of the complex numbers
when using the complex versions of the PETSc libraries; however, when
working <em>only</em> with real numbers in a code, one should use a version of
PETSc for real numbers for best efficiency.</p>
<p>The program
<a href="../src/ksp/ksp/tutorials/ex11.c.html">KSP Tutorial ex11</a>
solves a linear system with a complex coefficient matrix. Its Fortran
counterpart is
<a href="../src/ksp/ksp/tutorials/ex11f.F90.html">KSP Tutorial ex11f</a>.</p>
</section>
<section id="parallel-communication">
<h2>Parallel Communication<a class="headerlink" href="#parallel-communication" title="Link to this heading">#</a></h2>
<p>When used in a message-passing environment, all communication within
PETSc is done through MPI, the message-passing interface standard
<span id="id4">[<a class="reference internal" href="getting_started.html#id1190" title="MPI Forum. MPI: a message-passing interface standard. International J. Supercomputing Applications, 1994.">For94</a>]</span>. Any file that includes <code class="docutils notranslate"><span class="pre">petscsys.h</span></code> (or
any other PETSc include file) can freely use any MPI routine.</p>
</section>
<section id="graphics">
<span id="sec-graphics"></span><h2>Graphics<a class="headerlink" href="#graphics" title="Link to this heading">#</a></h2>
<p>The PETSc graphics library is not intended to compete with high-quality
graphics packages. Instead, it is intended to be easy to use
interactively with PETSc programs. We urge users to generate their
publication-quality graphics using a professional graphics package. If a
user wants to hook certain packages into PETSc, he or she should send a
message to
<a class="reference external" href="mailto:petsc-maint&#37;&#52;&#48;mcs&#46;anl&#46;gov">petsc-maint<span>&#64;</span>mcs<span>&#46;</span>anl<span>&#46;</span>gov</a>; we
will see whether it is reasonable to try to provide direct interfaces.</p>
<section id="windows-as-petscviewers">
<h3>Windows as PetscViewers<a class="headerlink" href="#windows-as-petscviewers" title="Link to this heading">#</a></h3>
<p>For drawing predefined PETSc objects such as matrices and vectors, one
may first create a viewer using the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Viewer/PetscViewerDrawOpen.html">PetscViewerDrawOpen</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="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">display</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">title</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">w</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">h</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="o">*</span><span class="n">viewer</span><span class="p">);</span>
</pre></div>
</div>
<p>This viewer may be passed to any of the <code class="docutils notranslate"><span class="pre">XXXView()</span></code> routines.
Alternately, one may use command-line options to quickly specify viewer
formats, including <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span></code>-based ones; see
<a class="reference internal" href="#sec-viewfromoptions"><span class="std std-ref">Viewing From Options</span></a>.</p>
<p>To draw directly into the viewer, one must obtain the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span></code>
object with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscViewerDrawGetDraw.html">PetscViewerDrawGetDraw</a></span><span class="p">(</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="w"> </span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="o">*</span><span class="n">draw</span><span class="p">);</span>
</pre></div>
</div>
<p>Then one can call any of the <code class="docutils notranslate"><span class="pre">PetscDrawXXX()</span></code> commands on the <code class="docutils notranslate"><span class="pre">draw</span></code>
object. If one obtains the <code class="docutils notranslate"><span class="pre">draw</span></code> object in this manner, one does not
call the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawOpenX.html">PetscDrawOpenX</a>()</span></code> command discussed below.</p>
<p>Predefined viewers, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_DRAW_WORLD.html">PETSC_VIEWER_DRAW_WORLD</a></span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_DRAW_SELF.html">PETSC_VIEWER_DRAW_SELF</a></span></code>, may be used at any time. Their initial use
will cause the appropriate window to be created.</p>
<p>Implementations using OpenGL, TikZ, and other formats may be selected
with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawSetType.html">PetscDrawSetType</a>()</span></code>. PETSc can also produce movies; see
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawSetSaveMovie.html">PetscDrawSetSaveMovie</a>()</span></code>, and note that command-line options can also
be convenient; see the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawSetFromOptions.html">PetscDrawSetFromOptions</a>()</span></code> man page.</p>
<p>By default, PETSc drawing tools employ a private colormap, which
remedies the problem of poor color choices for contour plots due to an
external program’s mangling of the colormap. Unfortunately, this may
cause flashing of colors as the mouse is moved between the PETSc windows
and other windows. Alternatively, a shared colormap can be used via the
option <code class="docutils notranslate"><span class="pre">-draw_x_shared_colormap</span></code>.</p>
</section>
<section id="simple-petscdrawing">
<h3>Simple PetscDrawing<a class="headerlink" href="#simple-petscdrawing" title="Link to this heading">#</a></h3>
<p>With the default format, one can open a window that is not associated
with a viewer directly under the X11 Window System with the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawCreate.html">PetscDrawCreate</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="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">display</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">title</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">w</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">h</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="o">*</span><span class="n">win</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Draw/PetscDrawSetFromOptions.html">PetscDrawSetFromOptions</a></span><span class="p">(</span><span class="n">win</span><span class="p">);</span>
</pre></div>
</div>
<p>All drawing routines are performed relative to the window’s coordinate
system and viewport. By default, the drawing coordinates are from
<code class="docutils notranslate"><span class="pre">(0,0)</span></code> to <code class="docutils notranslate"><span class="pre">(1,1)</span></code>, where <code class="docutils notranslate"><span class="pre">(0,0)</span></code> indicates the lower left corner
of the window. The application program can change the window coordinates
with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawSetCoordinates.html">PetscDrawSetCoordinates</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">xl</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">yl</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">xr</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">yr</span><span class="p">);</span>
</pre></div>
</div>
<p>By default, graphics will be drawn in the entire window. To restrict the
drawing to a portion of the window, one may use the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawSetViewPort.html">PetscDrawSetViewPort</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">xl</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">yl</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">xr</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">yr</span><span class="p">);</span>
</pre></div>
</div>
<p>These arguments, which indicate the fraction of the window in which the
drawing should be done, must satisfy
<span class="math">\(0 \leq {\tt xl} \leq {\tt xr} \leq 1\)</span> and
<span class="math">\(0 \leq {\tt yl} \leq {\tt yr} \leq 1.\)</span></p>
<p>To draw a line, one uses the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLine.html">PetscDrawLine</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">xl</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">yl</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">xr</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">yr</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">cl</span><span class="p">);</span>
</pre></div>
</div>
<p>The argument <code class="docutils notranslate"><span class="pre">cl</span></code> indicates the color (which is an integer between 0
and 255) of the line. A list of predefined colors may be found in
<code class="docutils notranslate"><span class="pre">include/petscdraw.h</span></code> and includes <code class="docutils notranslate"><span class="pre">PETSC_DRAW_BLACK</span></code>,
<code class="docutils notranslate"><span class="pre">PETSC_DRAW_RED</span></code>, <code class="docutils notranslate"><span class="pre">PETSC_DRAW_BLUE</span></code> etc.</p>
<p>To ensure that all graphics actually have been displayed, one should use
the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawFlush.html">PetscDrawFlush</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</span><span class="p">);</span>
</pre></div>
</div>
<p>When displaying by using double buffering, which is set with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawSetDoubleBuffer.html">PetscDrawSetDoubleBuffer</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</span><span class="p">);</span>
</pre></div>
</div>
<p><em>all</em> processes must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawFlush.html">PetscDrawFlush</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</span><span class="p">);</span>
</pre></div>
</div>
<p>in order to swap the buffers. From the options database one may use
<code class="docutils notranslate"><span class="pre">-draw_pause</span></code> <code class="docutils notranslate"><span class="pre">n</span></code>, which causes the PETSc application to pause <code class="docutils notranslate"><span class="pre">n</span></code>
seconds at each <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawPause.html">PetscDrawPause</a>()</span></code>. A time of <code class="docutils notranslate"><span class="pre">-1</span></code> indicates that
the application should pause until receiving mouse input from the user.</p>
<p>Text can be drawn with commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawString.html">PetscDrawString</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">x</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">y</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">color</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">text</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Draw/PetscDrawStringVertical.html">PetscDrawStringVertical</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">x</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">y</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">color</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">text</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Draw/PetscDrawStringCentered.html">PetscDrawStringCentered</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">x</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">y</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">color</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">text</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Draw/PetscDrawStringBoxed.html">PetscDrawStringBoxed</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">draw</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">sxl</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">syl</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">sc</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">bc</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">text</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="o">*</span><span class="n">w</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="o">*</span><span class="n">h</span><span class="p">);</span>
</pre></div>
</div>
<p>The user can set the text font size or determine it with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawStringSetSize.html">PetscDrawStringSetSize</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">width</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">height</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Draw/PetscDrawStringGetSize.html">PetscDrawStringGetSize</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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="o">*</span><span class="n">width</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="o">*</span><span class="n">height</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="line-graphs">
<h3>Line Graphs<a class="headerlink" href="#line-graphs" title="Link to this heading">#</a></h3>
<p>PETSc includes a set of routines for manipulating simple two-dimensional
graphs. These routines, which begin with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Draw/PetscDrawAxisDraw.html">PetscDrawAxisDraw</a>()</span></code>, are
usually not used directly by the application programmer. Instead, the
programmer employs the line graph routines to draw simple line graphs.
As shown in the <a class="reference internal" href="#listing-draw-test-ex3"><span class="std std-ref">listing below</span></a>, line
graphs are created with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGCreate.html">PetscDrawLGCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDraw.html">PetscDraw</a></span><span class="w"> </span><span class="n">win</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">ncurves</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></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">ncurves</span></code> indicates how many curves are to be drawn.
Points can be added to each of the curves with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGAddPoint.html">PetscDrawLGAddPoint</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="n">ctx</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="o">*</span><span class="n">x</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="o">*</span><span class="n">y</span><span class="p">);</span>
</pre></div>
</div>
<p>The arguments <code class="docutils notranslate"><span class="pre">x</span></code> and <code class="docutils notranslate"><span class="pre">y</span></code> are arrays containing the next point value
for each curve. Several points for each curve may be added with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGAddPoints.html">PetscDrawLGAddPoints</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">**</span><span class="n">x</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="o">**</span><span class="n">y</span><span class="p">);</span>
</pre></div>
</div>
<p>The line graph is drawn (or redrawn) with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGDraw.html">PetscDrawLGDraw</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>A line graph that is no longer needed can be destroyed with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGDestroy.html">PetscDrawLGDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>To plot new curves, one can reset a linegraph with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGReset.html">PetscDrawLGReset</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>The line graph automatically determines the range of values to display
on the two axes. The user can change these defaults with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGSetLimits.html">PetscDrawLGSetLimits</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="n">ctx</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">xmin</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">xmax</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">ymin</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">ymax</span><span class="p">);</span>
</pre></div>
</div>
<p>It is also possible to change the display of the axes and to label them.
This procedure is done by first obtaining the axes context with the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawLGGetAxis.html">PetscDrawLGGetAxis</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Draw/PetscDrawAxis.html">PetscDrawAxis</a></span><span class="w"> </span><span class="o">*</span><span class="n">axis</span><span class="p">);</span>
</pre></div>
</div>
<p>One can set the axes’ colors and labels, respectively, by using the
commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Draw/PetscDrawAxisSetColors.html">PetscDrawAxisSetColors</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawAxis.html">PetscDrawAxis</a></span><span class="w"> </span><span class="n">axis</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">axis_lines</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">ticks</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">text</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Draw/PetscDrawAxisSetLabels.html">PetscDrawAxisSetLabels</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawAxis.html">PetscDrawAxis</a></span><span class="w"> </span><span class="n">axis</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">top</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">x</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">y</span><span class="p">);</span>
</pre></div>
</div>
<p>It is possible to turn off all graphics with the option <code class="docutils notranslate"><span class="pre">-nox</span></code>. This
will prevent any windows from being opened or any drawing actions to be
done. This is useful for running large jobs when the graphics overhead
is too large, or for timing.</p>
<p>The full example, <a href="../src/sys/classes/draw/tests/ex3.c.html">Draw Test ex3</a>,
follows.</p>
<div class="admonition-listing-src-classes-draw-tests-ex3-c admonition" id="snes-ex1">
<span id="listing-draw-test-ex3"></span><p class="admonition-title">Listing: <code class="docutils notranslate"><span class="pre">src/classes/draw/tests/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;Plots a simple line graph.</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">;</span>

<span class="cp">#if defined(PETSC_APPLE_FRAMEWORK)</span>
<span class="w">  </span><span class="cp">#import &lt;PETSc/petscsys.h&gt;</span>
<span class="w">  </span><span class="cp">#import &lt;PETSc/petscdraw.h&gt;</span>
<span class="cp">#else</span>

<span class="w">  </span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscsys.h&gt;</span>
<span class="w">  </span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;petscdraw.h&gt;</span>
<span class="cp">#endif</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/Draw/PetscDraw.html">PetscDraw</a></span><span class="w">           </span><span class="n">draw</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Draw/PetscDrawLG.html">PetscDrawLG</a></span><span class="w">         </span><span class="n">lg</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Draw/PetscDrawAxis.html">PetscDrawAxis</a></span><span class="w">       </span><span class="n">axis</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w">            </span><span class="n">n</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">15</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">nports</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="kt">int</span><span class="w">                 </span><span class="n">x</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">y</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">width</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">400</span><span class="p">,</span><span class="w"> </span><span class="n">height</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">300</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">useports</span><span class="p">,</span><span class="w"> </span><span class="n">flg</span><span class="p">;</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w">         </span><span class="o">*</span><span class="n">xlabel</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">ylabel</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">toplabel</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">legend</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">xd</span><span class="p">,</span><span class="w"> </span><span class="n">yd</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Draw/PetscDrawViewPorts.html">PetscDrawViewPorts</a></span><span class="w"> </span><span class="o">*</span><span class="n">ports</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>

<span class="w">  </span><span class="n">toplabel</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Top Label&quot;</span><span class="p">;</span>
<span class="w">  </span><span class="n">xlabel</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;X-axis Label&quot;</span><span class="p">;</span>
<span class="w">  </span><span class="n">ylabel</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Y-axis Label&quot;</span><span class="p">;</span>
<span class="w">  </span><span class="n">legend</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;Legend&quot;</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/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscOptionsGetMPIInt.html">PetscOptionsGetMPIInt</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;-x&quot;</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="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/PetscOptionsGetMPIInt.html">PetscOptionsGetMPIInt</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;-y&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">y</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/PetscOptionsGetMPIInt.html">PetscOptionsGetMPIInt</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;-width&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">width</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/PetscOptionsGetMPIInt.html">PetscOptionsGetMPIInt</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;-height&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">height</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/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"><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;-nports&quot;</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">nports</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">useports</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;-nolegend&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="n">legend</span><span class="w"> </span><span class="o">=</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/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;-notoplabel&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="n">toplabel</span><span class="w"> </span><span class="o">=</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/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;-noxlabel&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="n">xlabel</span><span class="w"> </span><span class="o">=</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/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;-noylabel&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="n">ylabel</span><span class="w"> </span><span class="o">=</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/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;-nolabels&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">toplabel</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
<span class="w">    </span><span class="n">xlabel</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
<span class="w">    </span><span class="n">ylabel</span><span class="w">   </span><span class="o">=</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/Draw/PetscDrawCreate.html">PetscDrawCreate</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="s">&quot;Title&quot;</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">y</span><span class="p">,</span><span class="w"> </span><span class="n">width</span><span class="p">,</span><span class="w"> </span><span class="n">height</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">draw</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/Draw/PetscDrawSetFromOptions.html">PetscDrawSetFromOptions</a></span><span class="p">(</span><span class="n">draw</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">useports</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/Draw/PetscDrawViewPortsCreate.html">PetscDrawViewPortsCreate</a></span><span class="p">(</span><span class="n">draw</span><span class="p">,</span><span class="w"> </span><span class="n">nports</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ports</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/Draw/PetscDrawViewPortsSet.html">PetscDrawViewPortsSet</a></span><span class="p">(</span><span class="n">ports</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="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Draw/PetscDrawLGCreate.html">PetscDrawLGCreate</a></span><span class="p">(</span><span class="n">draw</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">lg</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/Draw/PetscDrawLGSetUseMarkers.html">PetscDrawLGSetUseMarkers</a></span><span class="p">(</span><span class="n">lg</span><span class="p">,</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/Draw/PetscDrawLGGetAxis.html">PetscDrawLGGetAxis</a></span><span class="p">(</span><span class="n">lg</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">axis</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/Draw/PetscDrawAxisSetColors.html">PetscDrawAxisSetColors</a></span><span class="p">(</span><span class="n">axis</span><span class="p">,</span><span class="w"> </span><span class="n">PETSC_DRAW_BLACK</span><span class="p">,</span><span class="w"> </span><span class="n">PETSC_DRAW_RED</span><span class="p">,</span><span class="w"> </span><span class="n">PETSC_DRAW_BLUE</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/Draw/PetscDrawAxisSetLabels.html">PetscDrawAxisSetLabels</a></span><span class="p">(</span><span class="n">axis</span><span class="p">,</span><span class="w"> </span><span class="n">toplabel</span><span class="p">,</span><span class="w"> </span><span class="n">xlabel</span><span class="p">,</span><span class="w"> </span><span class="n">ylabel</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/Draw/PetscDrawLGSetLegend.html">PetscDrawLGSetLegend</a></span><span class="p">(</span><span class="n">lg</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">legend</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/Draw/PetscDrawLGSetFromOptions.html">PetscDrawLGSetFromOptions</a></span><span class="p">(</span><span class="n">lg</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="mi">0</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">n</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">xd</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">i</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">yd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">xd</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">xd</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/Draw/PetscDrawLGAddPoint.html">PetscDrawLGAddPoint</a></span><span class="p">(</span><span class="n">lg</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xd</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">yd</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/Draw/PetscDrawLGDraw.html">PetscDrawLGDraw</a></span><span class="p">(</span><span class="n">lg</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/Draw/PetscDrawLGSave.html">PetscDrawLGSave</a></span><span class="p">(</span><span class="n">lg</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/Draw/PetscDrawViewPortsDestroy.html">PetscDrawViewPortsDestroy</a></span><span class="p">(</span><span class="n">ports</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/Draw/PetscDrawLGDestroy.html">PetscDrawLGDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">lg</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/Draw/PetscDrawDestroy.html">PetscDrawDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">draw</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>

</pre></div>
</div>
</div>
</section>
<section id="graphical-convergence-monitor">
<h3>Graphical Convergence Monitor<a class="headerlink" href="#graphical-convergence-monitor" title="Link to this heading">#</a></h3>
<p>For both the linear and nonlinear solvers default routines allow one to
graphically monitor convergence of the iterative method. These are
accessed via the command line with <code class="docutils notranslate"><span class="pre">-ksp_monitor</span> <span class="pre">draw::draw_lg</span></code> and
<code class="docutils notranslate"><span class="pre">-snes_monitor</span> <span class="pre">draw::draw_lg</span></code>. See also
<a class="reference internal" href="ksp.html#sec-kspmonitor"><span class="std std-ref">Convergence Monitoring</span></a> and <a class="reference internal" href="snes.html#sec-snesmonitor"><span class="std std-ref">Convergence Monitoring</span></a>.</p>
</section>
<section id="disabling-graphics-at-compile-time">
<h3>Disabling Graphics at Compile Time<a class="headerlink" href="#disabling-graphics-at-compile-time" title="Link to this heading">#</a></h3>
<p>To disable all X-window-based graphics, run <code class="docutils notranslate"><span class="pre">configure</span></code> with the
additional option <code class="docutils notranslate"><span class="pre">--with-x=0</span></code></p>
</section>
</section>
</section>
<section class="tex2jax_ignore mathjax_ignore" id="developer-environments">
<span id="sec-developer-environments"></span><h1>Developer Environments<a class="headerlink" href="#developer-environments" title="Link to this heading">#</a></h1>
<section id="emacs-users">
<h2>Emacs Users<a class="headerlink" href="#emacs-users" title="Link to this heading">#</a></h2>
<p>Many PETSc developers use Emacs, which can be used as a “simple” text editor or a comprehensive development environment.
For a more integrated development environment, we recommend using <a class="reference external" href="https://emacs-lsp.github.io/lsp-mode/">lsp-mode</a> (or <a class="reference external" href="https://github.com/joaotavora/eglot">eglot</a>) with <a class="reference external" href="https://clangd.llvm.org/">clangd</a>.
The most convenient way to teach clangd what compilation flags to use is to install <a class="reference external" href="https://github.com/rizsotto/Bear">Bear</a> (“build ear”) and run:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">bear</span><span class="w"> </span><span class="n">make</span><span class="w"> </span><span class="o">-</span><span class="n">B</span>
</pre></div>
</div>
<p>which will do a complete rebuild (<code class="docutils notranslate"><span class="pre">-B</span></code>) of PETSc and capture the compilation commands in a file named <code class="docutils notranslate"><span class="pre">compile_commands.json</span></code>, which will be automatically picked up by clangd.
You can use the same procedure when building examples or your own project.
It can also be used with any other editor that supports clangd, including VS Code and Vim.
When lsp-mode is accompanied by <a class="reference external" href="https://www.flycheck.org/en/latest/">flycheck</a>, Emacs will provide real-time feedback and syntax checking, along with refactoring tools provided by clangd.</p>
<p>The easiest way to install packages in recent Emacs is to use the “Options” menu to select “Manage Emacs Packages”.</p>
<section id="tags">
<h3>Tags<a class="headerlink" href="#tags" title="Link to this heading">#</a></h3>
<p>It is sometimes useful to cross-reference tags across projects.
Regardless of whether you use lsp-mode, it can be useful to use <a class="reference external" href="https://www.gnu.org/software/global/">GNU Global</a> (install <code class="docutils notranslate"><span class="pre">gtags</span></code>) to provide reverse lookups (e.g. find all call sites
for a given function) across all projects you might work on/browse.
Tags for PETSc can be generated by running <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">allgtags</span></code> from <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code>, or one can generate tags for all projects by running a command such as</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>find $PETSC_DIR/{include,src,tutorials,$PETSC_ARCH/include} any/other/paths \
   -regex &#39;.*\.\(cc\|hh\|cpp\|cxx\|C\|hpp\|c\|h\|cu\)$&#39; \
   | grep -v ftn-auto | gtags -f -
</pre></div>
</div>
<p>from your home directory or wherever you keep source code. If you are
making large changes, it is useful to either set this up to run as a
cron job or to make a convenient alias so that refreshing is easy. Then
add the following to <code class="docutils notranslate"><span class="pre">~/.emacs</span></code> to enable gtags and specify key bindings.</p>
<div class="highlight-emacs notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nb">when</span><span class="w"> </span><span class="p">(</span><span class="nb">require</span><span class="w"> </span><span class="ss">&#39;gtags</span><span class="p">)</span>
<span class="w">  </span><span class="p">(</span><span class="nv">global-set-key</span><span class="w"> </span><span class="p">(</span><span class="nv">kbd</span><span class="w"> </span><span class="s">&quot;C-c f&quot;</span><span class="p">)</span><span class="w"> </span><span class="ss">&#39;gtags-find-file</span><span class="p">)</span>
<span class="w">  </span><span class="p">(</span><span class="nv">global-set-key</span><span class="w"> </span><span class="p">(</span><span class="nv">kbd</span><span class="w"> </span><span class="s">&quot;C-c .&quot;</span><span class="p">)</span><span class="w"> </span><span class="ss">&#39;gtags-find-tag</span><span class="p">)</span>
<span class="w">  </span><span class="p">(</span><span class="nv">global-set-key</span><span class="w"> </span><span class="p">(</span><span class="nv">kbd</span><span class="w"> </span><span class="s">&quot;C-c r&quot;</span><span class="p">)</span><span class="w"> </span><span class="ss">&#39;gtags-find-rtag</span><span class="p">)</span>
<span class="w">  </span><span class="p">(</span><span class="nv">global-set-key</span><span class="w"> </span><span class="p">(</span><span class="nv">kbd</span><span class="w"> </span><span class="s">&quot;C-c ,&quot;</span><span class="p">)</span><span class="w"> </span><span class="ss">&#39;gtags-pop-stack</span><span class="p">))</span>
<span class="p">(</span><span class="nv">add-hook</span><span class="w"> </span><span class="ss">&#39;c-mode-common-hook</span>
<span class="w">          </span><span class="o">&#39;</span><span class="p">(</span><span class="nb">lambda</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">(</span><span class="nv">gtags-mode</span><span class="w"> </span><span class="no">t</span><span class="p">)))</span><span class="w"> </span><span class="c1">; Or add to existing hook</span>
</pre></div>
</div>
<p>A more basic alternative to the GNU Global (<code class="docutils notranslate"><span class="pre">gtags</span></code>) approach that does not require adding packages is to use
the builtin <code class="docutils notranslate"><span class="pre">etags</span></code> feature. First, run <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">alletags</span></code> from the
PETSc home directory to generate the file <code class="docutils notranslate"><span class="pre">$PETSC_DIR/TAGS</span></code>, and
then from within Emacs, run</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>M-x visit-tags-table
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">M</span></code> denotes the Emacs Meta key, and enter the name of the
<code class="docutils notranslate"><span class="pre">TAGS</span></code> file. Then the command <code class="docutils notranslate"><span class="pre">M-.</span></code> will cause Emacs to find the
file and line number where a desired PETSc function is defined. Any
string in any of the PETSc files can be found with the command <code class="docutils notranslate"><span class="pre">M-x</span> <span class="pre">tags-search</span></code>.
To find repeated occurrences, one can simply use <code class="docutils notranslate"><span class="pre">M-,</span></code> to find the next occurrence.</p>
</section>
</section>
<section id="vs-code-users">
<h2>VS Code Users<a class="headerlink" href="#vs-code-users" title="Link to this heading">#</a></h2>
<p><a class="reference external" href="https://code.visualstudio.com/">VS Code</a> (unlike <a class="reference internal" href="#sec-visual-studio"><span class="std std-ref">Visual Studio Users</span></a>, described below) is an open-source editor with a rich extension ecosystem.
It has <a class="reference external" href="https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd">excellent integration</a> with clangd and will automatically pick up <code class="docutils notranslate"><span class="pre">compile_commands.json</span></code>
as produced by a command such as <code class="docutils notranslate"><span class="pre">bear</span> <span class="pre">make</span> <span class="pre">-B</span></code> (see <a class="reference internal" href="#sec-developer-environments"><span class="std std-ref">Developer Environments</span></a>).
If you have no prior attachment to a specific code editor, we recommend trying VS Code.</p>
</section>
<section id="vi-and-vim-users">
<h2>Vi and Vim Users<a class="headerlink" href="#vi-and-vim-users" title="Link to this heading">#</a></h2>
<p>This section lists helpful Vim commands for PETSc. Ones that configure Vim can be placed
in a <code class="docutils notranslate"><span class="pre">.vimrc</span></code> file in the top of the PETSc directory and will be loaded automatically.</p>
<p>Vim has configurable keymaps: all of the “command mode” commands given that start with
a colon (such as <code class="docutils notranslate"><span class="pre">:help</span></code>) can be assigned to short sequences in “normal mode,” which
is how most Vim users use their most frequently used commands.</p>
<p>See the <a class="reference internal" href="#sec-developer-environments"><span class="std std-ref">Developer Environments</span></a> discussion above for configuration of clangd, which
provides integrated development environment.</p>
<section id="id5">
<h3>Tags<a class="headerlink" href="#id5" title="Link to this heading">#</a></h3>
<p>The <code class="docutils notranslate"><span class="pre">tags</span></code> feature can be used to search PETSc files quickly and efficiently.
To use this feature, one should first check if the file, <code class="docutils notranslate"><span class="pre">$PETSC_DIR/CTAGS</span></code>
exists. If this file is not present, it should be generated by running <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">alletags</span></code> from the PETSc home directory. Once the file exists, from Vi/Vim the
user should issue the command</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>:set tags=CTAGS
</pre></div>
</div>
<p>from the <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code> directory and enter the name of the <code class="docutils notranslate"><span class="pre">CTAGS</span></code> file. The
command <code class="docutils notranslate"><span class="pre">:tag</span> <span class="pre">functionname</span></code> will cause Vi/Vim to open the file and line
number where a desired PETSc function is defined in the current window.
<code class="docutils notranslate"><span class="pre">&lt;Ctrl-o&gt;</span></code> will return the screen to your previous location.</p>
<p>The command <code class="docutils notranslate"><span class="pre">:stag</span> <span class="pre">functionname</span></code> will split the current window and then open
the file and line number for that function in one half. Some prefer this because
it is easier to compare the file you are editing to the function definition this way.</p>
</section>
<section id="cscope-and-gtags">
<h3>Cscope and gtags<a class="headerlink" href="#cscope-and-gtags" title="Link to this heading">#</a></h3>
<p>Vim can also use the <code class="docutils notranslate"><span class="pre">cscope</span></code> utility to navigate source code. One useful thing
it can do that the basic <code class="docutils notranslate"><span class="pre">tags</span></code> feature can’t is search for references to a symbol,
rather than its definition, which can be useful for refactoring. The command</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>:cs find s functionname
</pre></div>
</div>
<p>opens a list of all of the places the function is called in PETSc, and opens
the file and line that you choose. The variant <code class="docutils notranslate"><span class="pre">:scs</span> <span class="pre">find</span> <span class="pre">s</span> <span class="pre">functionname</span></code>
does the same but splits the window like <code class="docutils notranslate"><span class="pre">stag</span></code>.</p>
<p>The PETSc makefile does not have a command for building a cscope database, but
GNU Global is cross-compatible with cscope: call <code class="docutils notranslate"><span class="pre">make</span> <span class="pre">allgtags</span></code> to make the
gtags database, and run the commands</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>:set csprg=gtags-cscope
:cs add GTAGS
</pre></div>
</div>
</section>
<section id="quickfix">
<h3>Quickfix<a class="headerlink" href="#quickfix" title="Link to this heading">#</a></h3>
<p>Rather than exiting editing a file to build the library and check for errors or
warnings, calling <code class="docutils notranslate"><span class="pre">:make</span></code> runs the make command without leaving Vim and
collects the errors and warnings in a “quickfix” window. Move the cursor to
one of the errors or warnings in the quickfix window and press <code class="docutils notranslate"><span class="pre">&lt;Enter&gt;</span></code> and
the main window will jump to the file and line with the error. The following
commands filter lines of out PETSc’s make output that can clutter the quickfix window:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>:set efm^=%-GStarting\ make\ run\ on\ %.%#
:set efm^=%-GMachine\ characteristics:\ %.%#
:set efm^=%-G#define\ PETSC%.%#
</pre></div>
</div>
</section>
<section id="autocompletion-and-snippets">
<h3>Autocompletion and snippets<a class="headerlink" href="#autocompletion-and-snippets" title="Link to this heading">#</a></h3>
<p>Autocompletion of long function names can be helpful when working with PETSc.
If you have a tags file, you can press <code class="docutils notranslate"><span class="pre">&lt;Ctrl-N&gt;</span></code> when you have partially
typed a word to bring up a list of potential completions that you can choose
from with <code class="docutils notranslate"><span class="pre">&lt;Tab&gt;</span></code>.</p>
<p>More powerful autocompletion, such as completing the fieldname of a struct, is
available from external plugins that can be added to Vim, such as <a class="reference external" href="https://github.com/ervandew/supertab">SuperTab</a>, <a class="reference external" href="https://github.com/ackyshake/VimCompletesMe">VimCompletesMe</a>, or <a class="reference external" href="https://github.com/ycm-core/YouCompleteMe">YouCompleteMe</a>.</p>
<p>Along the same lines, plugins can be added that fill in the boilerplate
associated with PETSc programming with code snippets. One such tool is
<a class="reference external" href="https://github.com/sirver/UltiSnips">UltiSnips</a>.</p>
</section>
<section id="lsp-for-vim">
<h3>LSP for Vim<a class="headerlink" href="#lsp-for-vim" title="Link to this heading">#</a></h3>
<p>Several plugins provide the equivalent of emacs’ lsp-mode: YouCompleteMe,
mentioned above, is one; another popular one is <a class="reference external" href="https://github.com/dense-analysis/ale">ale</a>. These can check for syntax errors,
check for compilation errors in the background, and provide sophisticated tools
for refactoring. Like lsp-mode, they also rely on a compilation database, so
<code class="docutils notranslate"><span class="pre">bear</span> <span class="pre">--</span> <span class="pre">make</span> <span class="pre">-B</span></code> should be used as well to generate the file
<code class="docutils notranslate"><span class="pre">compile_commands.json</span></code>.</p>
<p>See <a class="reference external" href="http://www.yolinux.com/TUTORIALS/LinuxTutorialAdvanced_vi.html">online tutorials</a>
for additional Vi/Vim options.</p>
</section>
</section>
<section id="eclipse-users">
<h2>Eclipse Users<a class="headerlink" href="#eclipse-users" title="Link to this heading">#</a></h2>
<p>If you are interested in developing code that uses PETSc from Eclipse or
developing PETSc in Eclipse and have knowledge of how to do indexing and
build libraries in Eclipse, please contact us at
<a class="reference external" href="mailto:petsc-dev&#37;&#52;&#48;mcs&#46;anl&#46;gov">petsc-dev<span>&#64;</span>mcs<span>&#46;</span>anl<span>&#46;</span>gov</a>.</p>
<p>One way to index and build PETSc in Eclipse is as follows.</p>
<ol class="arabic simple">
<li><p>Open
“File<span class="math">\(\rightarrow\)</span>Import<span class="math">\(\rightarrow\)</span>Git<span class="math">\(\rightarrow\)</span>Projects
from Git”. In the next two panels, you can either add your existing
local repository or download PETSc from Bitbucket by providing the
URL. Most Eclipse distributions come with Git support. If not,
install the EGit plugin. When importing the project, select the
wizard “Import as general project”.</p></li>
<li><p>Right-click on the project (or the “File” menu on top) and select
“New <span class="math">\(\rightarrow\)</span> Convert to a C/C++ Project (Adds C/C++
Nature)”. In the setting window, choose “C Project” and specify the
project type as “Shared Library”.</p></li>
<li><p>Right-click on the C project and open the “Properties” panel. Under
“C/C++ Build <span class="math">\(\rightarrow\)</span> Builder Settings”, set the Build
directory to <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code> and make sure “Generate Makefiles
automatically” is unselected. Under the section “C/C++
General<span class="math">\(\rightarrow\)</span>Paths and Symbols”, add the PETSc paths
to “Includes”.</p></li>
</ol>
<blockquote>
<div><div class="highlight-none notranslate"><div class="highlight"><pre><span></span>     $PETSC_DIR/include
     $PETSC_DIR/$PETSC_ARCH/include

Under the section “C/C++ General\ :math:`\rightarrow`\ index”, choose
“Use active build configuration”.
</pre></div>
</div>
</div></blockquote>
<ol class="arabic simple">
<li><p>Configure PETSc normally outside Eclipse to generate a makefile and
then build the project in Eclipse. The source code will be parsed by
Eclipse.</p></li>
</ol>
<p>If you launch Eclipse from the Dock on Mac OS X, <code class="docutils notranslate"><span class="pre">.bashrc</span></code> will not be
loaded (a known OS X behavior, for security reasons). This will be a
problem if you set the environment variables <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code> and
<code class="docutils notranslate"><span class="pre">$PETSC_ARCH</span></code> in <code class="docutils notranslate"><span class="pre">.bashrc</span></code>. A solution which involves replacing the
executable can be found at
<code class="docutils notranslate"><span class="pre">`/questions/829749/launch-mac-eclipse-with-environment-variables-set</span></code> &lt;/questions/829749/launch-mac-eclipse-with-environment-variables-set&gt;`__.
Alternatively, you can add <code class="docutils notranslate"><span class="pre">$PETSC_DIR</span></code> and <code class="docutils notranslate"><span class="pre">$PETSC_ARCH</span></code> manually
under “Properties <span class="math">\(\rightarrow\)</span> C/C++ Build <span class="math">\(\rightarrow\)</span>
Environment”.</p>
<p>To allow an Eclipse code to compile with the PETSc include files and
link with the PETSc libraries, a PETSc user has suggested the following.</p>
<ol class="arabic simple">
<li><p>Right-click on your C project and select “Properties
<span class="math">\(\rightarrow\)</span> C/C++ Build <span class="math">\(\rightarrow\)</span> Settings”</p></li>
<li><p>A new window on the righthand side appears with various settings
options. Select “Includes” and add the required PETSc paths,</p></li>
</ol>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$PETSC_DIR/include
$PETSC_DIR/$PETSC_ARCH/include
</pre></div>
</div>
<ol class="arabic simple">
<li><p>Select “Libraries” under the header Linker and set the library search
path:</p></li>
</ol>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>   $PETSC_DIR/$PETSC_ARCH/lib

and the libraries, for example
</pre></div>
</div>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>m, petsc, stdc++, mpichxx, mpich, lapack, blas, gfortran, dl, rt,gcc_s, pthread, X11
</pre></div>
</div>
<p>Another PETSc user has provided the following steps to build an Eclipse
index for PETSc that can be used with their own code, without compiling
PETSc source into their project.</p>
<ol class="arabic simple">
<li><p>In the user project source directory, create a symlink to the PETSC
<code class="docutils notranslate"><span class="pre">src/</span></code> directory.</p></li>
<li><p>Refresh the project explorer in Eclipse, so the new symlink is
followed.</p></li>
<li><p>Right-click on the project in the project explorer, and choose “Index
<span class="math">\(\rightarrow\)</span> Rebuild”. The index should now be built.</p></li>
<li><p>Right-click on the PETSc symlink in the project explorer, and choose
“Exclude from build…” to make sure Eclipse does not try to compile
PETSc with the project.</p></li>
</ol>
<p>For further examples of using Eclipse with a PETSc-based application,
see the documentation for LaMEM <a class="footnote-reference brackets" href="#lamem" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a>.</p>
</section>
<section id="qt-creator-users">
<h2>Qt Creator Users<a class="headerlink" href="#qt-creator-users" title="Link to this heading">#</a></h2>
<p>This information was provided by Mohammad Mirzadeh. The Qt Creator IDE
is part of the Qt SDK, developed for cross-platform GUI programming
using C++. It is available under GPL v3, LGPL v2 and a commercial
license and may be obtained, either as part of the Qt SDK or as
stand-alone software. It supports
automatic makefile generation using cross-platform <code class="docutils notranslate"><span class="pre">qmake</span></code> and
CMake build systems as well as allowing one to import projects based
on existing, possibly hand-written, makefiles. Qt Creator has a visual
debugger using GDB and LLDB (on Linux and OS X) or Microsoft’s CDB (on
Microsoft Windows) as backends. It also has an interface to Valgrind’s “memcheck”
and “callgrind” tools to detect memory leaks and profile code. It has
built-in support for a variety of version control systems including git,
mercurial, and subversion. Finally, Qt Creator comes fully equipped with
auto-completion, function look-up, and code refactoring tools. This
enables one to easily browse source files, find relevant functions, and
refactor them across an entire project.</p>
<section id="creating-a-project">
<h3>Creating a Project<a class="headerlink" href="#creating-a-project" title="Link to this heading">#</a></h3>
<p>When using Qt Creator with <code class="docutils notranslate"><span class="pre">qmake</span></code>, one needs a <code class="docutils notranslate"><span class="pre">.pro</span></code> file. This
configuration file tells Qt Creator about all build/compile options and
locations of source files. One may start with a blank <code class="docutils notranslate"><span class="pre">.pro</span></code> file and
fill in configuration options as needed. For example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># The name of the application executable
TARGET = ex1

# There are two ways to add PETSc functionality
# 1-Manual: Set all include path and libs required by PETSc
PETSC_INCLUDE = path/to/petsc_includes # e.g. obtained via running `make getincludedirs&#39;
PETSC_LIBS = path/to/petsc_libs # e.g. obtained via running `make getlinklibs&#39;

INCLUDEPATH += $$PETSC_INCLUDES
LIBS += $$PETSC_LIBS

# 2-Automatic: Use the PKGCONFIG functionality
# NOTE: petsc.pc must be in the pkgconfig path. You might need to adjust PKG_CONFIG_PATH
CONFIG += link_pkgconfig
PKGCONFIG += PETSc

# Set appropriate compiler and its flags
QMAKE_CC = path/to/mpicc
QMAKE_CXX = path/to/mpicxx # if this is a cpp project
QMAKE_LINK = path/to/mpicxx # if this is a cpp project

QMAKE_CFLAGS   += -O3 # add extra flags here
QMAKE_CXXFLAGS += -O3
QMAKE_LFLAGS   += -O3

# Add all files that must be compiled
SOURCES += ex1.c source1.c source2.cpp

HEADERS += source1.h source2.h

# OTHER_FILES are ignored during compilation but will be shown in file panel in Qt Creator
OTHER_FILES += \
    path/to/resource_file \
    path/to/another_file
</pre></div>
</div>
<p>In this example, keywords include:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">TARGET</span></code>: The name of the application executable.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">INCLUDEPATH</span></code>: Used at compile time to point to required include
files. Essentially, it is used as an <code class="docutils notranslate"><span class="pre">-I</span> <span class="pre">\$\$INCLUDEPATH</span></code> flag for
the compiler. This should include all application-specific header
files and those related to PETSc (which may be found via
<code class="docutils notranslate"><span class="pre">make</span> <span class="pre">getincludedirs</span></code>).</p></li>
<li><p><code class="docutils notranslate"><span class="pre">LIBS</span></code>: Defines all required external libraries to link with the
application. To get PETSc’s linking libraries, use
<code class="docutils notranslate"><span class="pre">make</span> <span class="pre">getlinklibs</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">CONFIG</span></code>: Configuration options to be used by <code class="docutils notranslate"><span class="pre">qmake</span></code>. Here, the
option <code class="docutils notranslate"><span class="pre">link_pkgconfig</span></code> instructs <code class="docutils notranslate"><span class="pre">qmake</span></code> to internally use
<code class="docutils notranslate"><span class="pre">pkgconfig</span></code> to resolve <code class="docutils notranslate"><span class="pre">INCLUDEPATH</span></code> and <code class="docutils notranslate"><span class="pre">LIBS</span></code> variables.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">PKGCONFIG</span></code>: Name of the configuration file (the <code class="docutils notranslate"><span class="pre">.pc</span></code> file –
here <code class="docutils notranslate"><span class="pre">petsc.pc</span></code>) to be passed to <code class="docutils notranslate"><span class="pre">pkgconfig</span></code>. Note that for this
functionality to work, <code class="docutils notranslate"><span class="pre">petsc.pc</span></code> must be in path which might
require adjusting the <code class="docutils notranslate"><span class="pre">PKG_CONFIG_PATH</span></code> environment variable. For
more information see
<a class="reference external" href="https://doc.qt.io/qtcreator/creator-build-settings.html">the Qt Creator documentation</a>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">QMAKE_CC</span></code> and <code class="docutils notranslate"><span class="pre">QMAKE_CXX</span></code>: Define which C/C++ compilers use.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">QMAKE_LINK</span></code>: Defines the proper linker to be used. Relevant if
compiling C++ projects.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">QMAKE_CFLAGS</span></code>, <code class="docutils notranslate"><span class="pre">QMAKE_CXXFLAGS</span></code> and <code class="docutils notranslate"><span class="pre">QMAKE_LFLAGS</span></code>: Set the
corresponding compile and linking flags.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">SOURCES</span></code>: Source files to be compiled.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">HEADERS</span></code>: Header files required by the application.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">OTHER_FILES</span></code>: Other files to include (source, header, or any other
extension). Note that none of the source files placed here are
compiled.</p></li>
</ul>
<p>More options can be included in a <code class="docutils notranslate"><span class="pre">.pro</span></code> file; see
<a class="reference external" href="https://doc.qt.io/qt-5/qmake-project-files.html">https://doc.qt.io/qt-5/qmake-project-files.html</a>. Once the <code class="docutils notranslate"><span class="pre">.pro</span></code> file
is generated, the user can simply open it via Qt Creator. Upon opening,
one has the option to create two different build options, debug and
release, and switch between the two. For more information on using the
Qt Creator interface and other more advanced aspects of the IDE, refer
to <a class="reference external" href="https://www.qt.io/qt-features-libraries-apis-tools-and-ide/">https://www.qt.io/qt-features-libraries-apis-tools-and-ide/</a></p>
</section>
</section>
<section id="visual-studio-users">
<span id="sec-visual-studio"></span><h2>Visual Studio Users<a class="headerlink" href="#visual-studio-users" title="Link to this heading">#</a></h2>
<p>To use PETSc from Microsoft Visual Studio, one would have to compile a PETSc
example with its corresponding makefile and then transcribe all compiler
and linker options used in this build into a Visual Studio project file,
in the appropriate format in Visual Studio project settings.</p>
</section>
<section id="xcode-ide-users">
<h2>Xcode IDE Users<a class="headerlink" href="#xcode-ide-users" title="Link to this heading">#</a></h2>
<p>See <a class="reference internal" href="../install/install.html#doc-macos-install"><span class="std std-ref">Installing On macOS</span></a> for the standard Unix command line tools approach to development on macOS. The information
below is only if you plan to write code within the Xcode IDE.</p>
<section id="apple-xcode-ide-for-macos-applications">
<h3>Apple Xcode IDE for macOS Applications<a class="headerlink" href="#apple-xcode-ide-for-macos-applications" title="Link to this heading">#</a></h3>
<p>Follow the instructions in <code class="docutils notranslate"><span class="pre">$PETSC_DIR/systems/Apple/OSX/bin/makeall</span></code>
to build the PETSc framework and documentation suitable for use in
Xcode.</p>
<p>You can then use the PETSc framework in
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/arch-osx/PETSc.framework</span></code> in the usual manner for Apple
frameworks. See the examples in
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/systems/Apple/OSX/examples</span></code>. When working in Xcode, things
like function name completion should work for all PETSc functions as
well as MPI functions. You must also link against the Apple
<code class="docutils notranslate"><span class="pre">Accelerate.framework</span></code>.</p>
</section>
<section id="apple-xcode-ide-for-iphone-ipad-ios-applications">
<h3>Apple Xcode IDE for iPhone/iPad iOS Applications<a class="headerlink" href="#apple-xcode-ide-for-iphone-ipad-ios-applications" title="Link to this heading">#</a></h3>
<p>Follow the instructions in
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/systems/Apple/iOS/bin/iosbuilder.py</span></code> to build the PETSc
library for use on the iPhone/iPad.</p>
<p>You can then use the PETSc static library in
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/arch-osx/libPETSc.a</span></code> in the usual manner for Apple
libraries inside your iOS XCode projects; see the examples in
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/systems/Apple/iOS/examples</span></code>. You must also link against
the Apple <code class="docutils notranslate"><span class="pre">Accelerate.framework</span></code>.</p>
<p>A thorough discussion of the
procedure is given in <a class="reference external" href="https://www.researchgate.net/publication/308973080_Comparison_of_Migration_Techniques_for_High-Performance_Code_to_Android_and_iOS">Comparison of Migration Techniques for High-Performance Code to Android and iOS</a>.</p>
<p>For Android, you must have your standalone bin folder in the path, so that the compilers
are visible.</p>
<p>The installation process has not been tested for iOS or Android since 2017.</p>
<p class="rubric">Footnotes</p>
</section>
</section>
</section>
<hr class="footnotes docutils" />
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="json" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>
<p>JSON is a subset of YAML</p>
</aside>
<aside class="footnote brackets" id="saws" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">2</a><span class="fn-bracket">]</span></span>
<p><a class="reference external" href="https://bitbucket.org/saws/saws/wiki/Home">Saws wiki on Bitbucket</a></p>
</aside>
<aside class="footnote brackets" id="cxx-note" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">3</a><span class="fn-bracket">]</span></span>
<p>Note that this option is not required to use PETSc with C++</p>
</aside>
<aside class="footnote brackets" id="lamem" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id6">4</a><span class="fn-bracket">]</span></span>
<p>See the <code class="docutils notranslate"><span class="pre">doc/</span></code> directory at <a class="reference external" href="https://bitbucket.org/bkaus/lamem">https://bitbucket.org/bkaus/lamem</a></p>
</aside>
</aside>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="blas-lapack.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">The Use of BLAS and LAPACK in PETSc and external libraries</p>
      </div>
    </a>
    <a class="right-next"
       href="advanced.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Advanced Features of Matrices and 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-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#">Other PETSc Features</a><ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#petsc-on-a-process-subset">PETSc on a process subset</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#runtime-options">Runtime Options</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#the-options-database">The Options Database</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#options-prefixes">Options Prefixes</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#adding-options-from-a-file">Adding options from a file</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#user-defined-petscoptions">User-Defined PetscOptions</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#keeping-track-of-options">Keeping Track of Options</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#viewers-looking-at-petsc-objects">Viewers: Looking at PETSc Objects</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#viewing-from-options">Viewing From Options</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#using-viewers-to-check-load-imbalance">Using Viewers to Check Load Imbalance</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-saws-with-petsc">Using SAWs with PETSc</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#debugging">Debugging</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#error-handling">Error Handling</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#numbers">Numbers</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#parallel-communication">Parallel Communication</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#graphics">Graphics</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#windows-as-petscviewers">Windows as PetscViewers</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#simple-petscdrawing">Simple PetscDrawing</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#line-graphs">Line Graphs</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#graphical-convergence-monitor">Graphical Convergence Monitor</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#disabling-graphics-at-compile-time">Disabling Graphics at Compile Time</a></li>
</ul>
</li>
</ul>
</li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#developer-environments">Developer Environments</a><ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#emacs-users">Emacs Users</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#tags">Tags</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#vs-code-users">VS Code Users</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#vi-and-vim-users">Vi and Vim Users</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#id5">Tags</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#cscope-and-gtags">Cscope and gtags</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#quickfix">Quickfix</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#autocompletion-and-snippets">Autocompletion and snippets</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#lsp-for-vim">LSP for Vim</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#eclipse-users">Eclipse Users</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#qt-creator-users">Qt Creator Users</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#creating-a-project">Creating a Project</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#visual-studio-users">Visual Studio Users</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#xcode-ide-users">Xcode IDE Users</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#apple-xcode-ide-for-macos-applications">Apple Xcode IDE for macOS Applications</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#apple-xcode-ide-for-iphone-ipad-ios-applications">Apple Xcode IDE for iPhone/iPad iOS Applications</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  </nav></div>

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

  
  <div class="tocsection editthispage">
    <a href="https://gitlab.com/petsc/petsc/-/edit/release/doc/manual/other.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/other.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>