File: vec.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 (2172 lines) | stat: -rw-r--r-- 318,303 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>Vectors and Parallel Data &#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/vec';</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="Matrices" href="mat.html" />
    <link rel="prev" title="The Solvers in PETSc/TAO" href="programming.html" />
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="docsearch:language" content="en"/>
    <meta name="docbuild:last-update" content="2025-04-30T13:10:40-0500 (v3.23.1)"/>
  </head>
  
  
  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">

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

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

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

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

  

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    </div>
  
  </header>

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

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

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

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

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

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

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

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

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

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

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

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

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






</ul>
</li>
<li class="toctree-l2 current active has-children"><a class="reference internal" href="programming.html">The Solvers in PETSc/TAO</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><ul class="current">
<li class="toctree-l3 current active"><a class="current reference internal" href="#">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 has-children"><a class="reference internal" href="additional.html">Additional Information</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-5"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l3"><a class="reference internal" href="fortran.html">PETSc for Fortran Users</a></li>
<li class="toctree-l3"><a class="reference internal" href="versionchecking.html">Checking the PETSc version</a></li>
<li class="toctree-l3"><a class="reference internal" href="matlab.html">Using MATLAB with PETSc</a></li>
<li class="toctree-l3"><a class="reference internal" href="profiling.html">Profiling</a></li>
<li class="toctree-l3"><a class="reference internal" href="performance.html">Hints for Performance Tuning</a></li>
<li class="toctree-l3"><a class="reference internal" href="streams.html">STREAMS: Example Study</a></li>
<li class="toctree-l3"><a class="reference internal" href="blas-lapack.html">The Use of BLAS and LAPACK in PETSc and external libraries</a></li>
<li class="toctree-l3"><a class="reference internal" href="other.html">Other PETSc Features</a></li>

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


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





<nav aria-label="Breadcrumb">
  <ul class="bd-breadcrumbs">
    
    <li class="breadcrumb-item breadcrumb-home">
      <a href="../index.html" class="nav-link" aria-label="Home">
        <i class="fa-solid fa-home"></i>
      </a>
    </li>
    
    <li class="breadcrumb-item"><a href="../overview/index.html" class="nav-link">Overview</a></li>
    
    
    <li class="breadcrumb-item"><i class="fa-solid fa-ellipsis"></i></li>
    
    
    <li class="breadcrumb-item"><a href="programming.html" class="nav-link">The Solvers in PETSc/TAO</a></li>
    
    <li class="breadcrumb-item active" aria-current="page">Vectors and...</li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="vectors-and-parallel-data">
<span id="ch-vectors"></span><h1>Vectors and Parallel Data<a class="headerlink" href="#vectors-and-parallel-data" title="Link to this heading">#</a></h1>
<p>Vectors (denoted by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code>) are used to store discrete PDE solutions, right-hand sides for
linear systems, etc. Users can create and manipulate entries in vectors directly with a basic, low-level interface or
they can use the PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> objects to connect actions on vectors to the type of discretization and grid that they are
working with. These higher-level interfaces handle much of the details of the interactions with vectors and hence, are preferred
in most situations. This chapter is organized as follows:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#sec-veccreate"><span class="std std-ref">Creating Vectors</span></a></p>
<ul>
<li><p>User managed</p></li>
<li><p><a class="reference internal" href="#sec-struct"><span class="std std-ref">DMDA - Creating vectors for structured grids</span></a></p></li>
<li><p><a class="reference internal" href="#sec-stag"><span class="std std-ref">DMSTAG - Creating vectors for staggered grids</span></a></p></li>
<li><p><a class="reference internal" href="#sec-unstruct"><span class="std std-ref">DMPLEX - Creating vectors for unstructured grids</span></a></p></li>
<li><p><a class="reference internal" href="#sec-network"><span class="std std-ref">DMNETWORK - Creating vectors for networks</span></a></p></li>
</ul>
</li>
<li><p>Setting vector values</p>
<ul>
<li><p>For generic vectors</p></li>
<li><p><a class="reference internal" href="#sec-struct-set"><span class="std std-ref">DMDA - Setting vector values</span></a></p></li>
<li><p><a class="reference internal" href="#sec-stag-set"><span class="std std-ref">DMSTAG - Setting vector values</span></a></p></li>
<li><p><a class="reference internal" href="#sec-unstruct-set"><span class="std std-ref">DMPLEX - Setting vector values</span></a></p></li>
<li><p><a class="reference internal" href="#sec-network-set"><span class="std std-ref">DMNETWORK - Setting vector values</span></a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#sec-vecbasic"><span class="std std-ref">Basic Vector Operations</span></a></p></li>
<li><p><a class="reference internal" href="#sec-localglobal"><span class="std std-ref">Local/global vectors and communicating between vectors</span></a></p></li>
<li><p><a class="reference internal" href="#sec-scatter"><span class="std std-ref">Low-level Vector Communication</span></a></p>
<ul>
<li><p><a class="reference internal" href="#sec-islocaltoglobalmap"><span class="std std-ref">Local to global mappings</span></a></p></li>
<li><p><a class="reference internal" href="#sec-vecghost"><span class="std std-ref">Global Vectors with locations for ghost values</span></a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#sec-ao"><span class="std std-ref">Application Orderings</span></a></p></li>
</ul>
<section id="creating-vectors">
<span id="sec-veccreate"></span><h2>Creating Vectors<a class="headerlink" href="#creating-vectors" title="Link to this heading">#</a></h2>
<p>PETSc provides many ways to create vectors. The most basic, where the user is responsible for managing the
parallel distribution of the vector entries, and a variety of higher-level approaches, based on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, for classes of problems such
as structured grids, staggered grids, unstructured grids, networks, and particles.</p>
<p>The most basic way to create a vector with a local size of <code class="docutils notranslate"><span class="pre">m</span></code> and a global size of <code class="docutils notranslate"><span class="pre">M</span></code>, is to
use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreate.html">VecCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">v</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecSetSizes.html">VecSetSizes</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">v</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">m</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">M</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecSetFromOptions.html">VecSetFromOptions</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">v</span><span class="p">);</span>
</pre></div>
</div>
<p>which automatically generates the appropriate vector type (sequential or
parallel) over all processes in <code class="docutils notranslate"><span class="pre">comm</span></code>. The option <code class="docutils notranslate"><span class="pre">-vec_type</span> <span class="pre">&lt;type&gt;</span></code>
can be used in conjunction with
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetFromOptions.html">VecSetFromOptions</a>()</span></code> to specify the use of a particular type of vector. For example, for NVIDIA GPU CUDA, use <code class="docutils notranslate"><span class="pre">cuda</span></code>.
The GPU-based vectors allow
one to set values on either the CPU or GPU but do their computations on the GPU.</p>
<p>We emphasize that all processes in <code class="docutils notranslate"><span class="pre">comm</span></code> <em>must</em> call the vector
creation routines since these routines are collective on all
processes in the communicator. If you are unfamiliar with MPI
communicators, see the discussion in <a class="reference internal" href="getting_started.html#sec-writing"><span class="std std-ref">Writing PETSc Programs</span></a>. In addition, if a sequence of creation routines is
used, they must be called in the same order for each process in the
communicator.</p>
<p>Instead of, or before calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetFromOptions.html">VecSetFromOptions</a>()</span></code>, one can call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSetType.html">VecSetType</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">v</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/VecType.html">VecType</a></span><span class="w"> </span><span class="o">&lt;</span><span class="n"><a href="../manualpages/Vec/VECCUDA.html">VECCUDA</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/VECHIP.html">VECHIP</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/VECKOKKOS.html">VECKOKKOS</a></span><span class="w"> </span><span class="n">etc</span><span class="o">&gt;</span><span class="p">)</span>
</pre></div>
</div>
<p>One can create vectors whose entries are stored on GPUs using the convenience routine,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreateMPICUDA.html">VecCreateMPICUDA</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">m</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>There are convenience creation routines for almost all vector types; we recommend using the more verbose form because it allows
selecting CPU or GPU simulations at runtime.</p>
<p>For applications running in parallel that involve multi-dimensional structured grids, unstructured grids, networks, etc, it is cumbersome for users to explicitly manage the needed local and global sizes of the vectors.
Hence, PETSc provides two powerful abstract objects (lower level) <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSection/PetscSection.html">PetscSection</a></span></code> (see <a class="reference internal" href="section.html#ch-petscsection"><span class="std std-ref">PetscSection: Connecting Grids to Data</span></a>) and (higher level) <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> (see <a class="reference internal" href="dmbase.html#ch-dmbase"><span class="std std-ref">DM Basics</span></a>) to help manage the vectors and matrices needed for such applications. Using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, parallel vectors can be created easily with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">dm</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">v</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> object, see <a class="reference internal" href="#sec-struct"><span class="std std-ref">DMDA - Creating vectors for structured grids</span></a>, <a class="reference internal" href="#sec-stag"><span class="std std-ref">DMSTAG - Creating vectors for staggered grids</span></a>, and <a class="reference internal" href="dmplex.html#ch-unstructured"><span class="std std-ref">DMPlex: Unstructured Grids</span></a> for more details on <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> for structured grids, staggered
structured grids, and for unstructured grids,
manages creating the correctly sized parallel vectors efficiently. One controls the type of vector that <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> creates by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMSetVecType.html">DMSetVecType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">dm</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/VecType.html">VecType</a></span><span class="w"> </span><span class="n">vt</span><span class="p">)</span>
</pre></div>
</div>
<p>or by calling <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMSetFromOptions.html">DMSetFromOptions</a>(<a href="../manualpages/DM/DM.html">DM</a></span> <span class="pre">dm)</span></code> and using the option <code class="docutils notranslate"><span class="pre">-dm_vec_type</span> <span class="pre">&lt;standard</span> <span class="pre">or</span> <span class="pre">cuda</span> <span class="pre">or</span> <span class="pre">kokkos</span> <span class="pre">etc&gt;</span></code></p>
<section id="dmda-creating-vectors-for-structured-grids">
<span id="sec-struct"></span><h3>DMDA - Creating vectors for structured grids<a class="headerlink" href="#dmda-creating-vectors-for-structured-grids" title="Link to this heading">#</a></h3>
<p>Each <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> type is suitable for a family of problems. The first of these, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>
are intended for use with <em>logically structured rectangular grids</em>
when communication of nonlocal data is needed before certain local
computations can occur. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> is designed only for
the case in which data can be thought of as being stored in a standard
multidimensional array; thus, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> are <em>not</em> intended for
parallelizing unstructured grid problems, etc.</p>
<p>For example, a typical situation one encounters in solving PDEs in
parallel is that, to evaluate a local function, <code class="docutils notranslate"><span class="pre">f(x)</span></code>, each process
requires its local portion of the vector <code class="docutils notranslate"><span class="pre">x</span></code> as well as its ghost
points (the bordering portions of the vector that are owned by
neighboring processes). Figure <a class="reference internal" href="#fig-ghosts"><span class="std std-ref">Ghost Points for Two Stencil Types on the Seventh Process</span></a> illustrates the
ghost points for the seventh process of a two-dimensional, structured
parallel grid. Each box represents a process; the ghost points for the
seventh process’s local part of a parallel array are shown in gray.</p>
<figure class="align-default" id="fig-ghosts">
<img alt="Ghost Points for Two Stencil Types on the Seventh Process" src="../_images/ghost.png" />
<figcaption>
<p><span class="caption-number">Fig. 3 </span><span class="caption-text">Ghost Points for Two Stencil Types on the Seventh Process</span><a class="headerlink" href="#fig-ghosts" title="Link to this image">#</a></p>
</figcaption>
</figure>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> object
contains parallel data layout information and communication
information and is used to create vectors and matrices with
the proper layout.</p>
<p>One creates a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> two
dimensions with the convenience routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDACreate2d.html">DMDACreate2d</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DMBoundaryType</a></span><span class="w"> </span><span class="n">xperiod</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DMBoundaryType</a></span><span class="w"> </span><span class="n">yperiod</span><span class="p">,</span><span class="n"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDAStencilType</a></span><span class="w"> </span><span class="n">st</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">m</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">dof</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">s</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">lx</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">ly</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="o">*</span><span class="n">da</span><span class="p">);</span>
</pre></div>
</div>
<p>The arguments <code class="docutils notranslate"><span class="pre">M</span></code> and <code class="docutils notranslate"><span class="pre">N</span></code> indicate the global numbers of grid points
in each direction, while <code class="docutils notranslate"><span class="pre">m</span></code> and <code class="docutils notranslate"><span class="pre">n</span></code> denote the process partition in
each direction; <code class="docutils notranslate"><span class="pre">m*n</span></code> must equal the number of processes in the MPI
communicator, <code class="docutils notranslate"><span class="pre">comm</span></code>. Instead of specifying the process layout, one
may use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span></code> for <code class="docutils notranslate"><span class="pre">m</span></code> and <code class="docutils notranslate"><span class="pre">n</span></code> so that PETSc will
select the partition. The type of periodicity of the array
is specified by <code class="docutils notranslate"><span class="pre">xperiod</span></code> and <code class="docutils notranslate"><span class="pre">yperiod</span></code>, which can be
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMBoundaryType.html">DM_BOUNDARY_NONE</a></span></code> (no periodicity), <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMBoundaryType.html">DM_BOUNDARY_PERIODIC</a></span></code>
(periodic in that direction), <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMBoundaryType.html">DM_BOUNDARY_TWIST</a></span></code> (periodic in that
direction, but identified in reverse order), <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMBoundaryType.html">DM_BOUNDARY_GHOSTED</a></span></code> ,
or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMBoundaryType.html">DM_BOUNDARY_MIRROR</a></span></code>. The argument <code class="docutils notranslate"><span class="pre">dof</span></code> indicates the number of
degrees of freedom at each array point, and <code class="docutils notranslate"><span class="pre">s</span></code> is the stencil width
(i.e., the width of the ghost point region). The optional arrays <code class="docutils notranslate"><span class="pre">lx</span></code>
and <code class="docutils notranslate"><span class="pre">ly</span></code> may contain the number of nodes along the x and y axis for
each cell, i.e. the dimension of <code class="docutils notranslate"><span class="pre">lx</span></code> is <code class="docutils notranslate"><span class="pre">m</span></code> and the dimension of
<code class="docutils notranslate"><span class="pre">ly</span></code> is <code class="docutils notranslate"><span class="pre">n</span></code>; alternately, <code class="docutils notranslate"><span class="pre">NULL</span></code> may be passed in.</p>
<p>Two types of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> communication data structures can be
created, as specified by <code class="docutils notranslate"><span class="pre">st</span></code>. Star-type stencils that radiate outward
only in the coordinate directions are indicated by
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_STAR</a></span></code>, while box-type stencils are specified by
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_BOX</a></span></code>. For example, for the two-dimensional case,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_STAR</a></span></code> with width 1 corresponds to the standard 5-point
stencil, while <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_BOX</a></span></code> with width 1 denotes the standard
9-point stencil. In both instances, the ghost points are identical, the
only difference being that with star-type stencils, certain ghost points
are ignored, substantially decreasing the number of messages sent. Note
that the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_STAR</a></span></code> stencils can save interprocess
communication in two and three dimensions.</p>
<p>These <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> stencils have nothing directly to do with a specific finite
difference stencil one might choose to use for discretization; they
only ensure that the correct values are in place for the application of a
user-defined finite difference stencil (or any other discretization
technique).</p>
<p>The commands for creating <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>
in one and three dimensions are analogous:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDACreate1d.html">DMDACreate1d</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DMBoundaryType</a></span><span class="w"> </span><span class="n">xperiod</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">w</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">s</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">lc</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="o">*</span><span class="n">inra</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDACreate3d.html">DMDACreate3d</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DMBoundaryType</a></span><span class="w"> </span><span class="n">xperiod</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DMBoundaryType</a></span><span class="w"> </span><span class="n">yperiod</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DMBoundaryType.html">DMBoundaryType</a></span><span class="w"> </span><span class="n">zperiod</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDAStencilType</a></span><span class="w"> </span><span class="n">stencil_type</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">P</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">m</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">p</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">w</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">s</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">lx</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">ly</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">lz</span><span class="p">,</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="o">*</span><span class="n">inra</span><span class="p">);</span>
</pre></div>
</div>
<p>The routines to create a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> are collective so that all
processes in the communicator <code class="docutils notranslate"><span class="pre">comm</span></code> must call the same creation routines in the same order.</p>
<p>A <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> may be created, and its type set with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMCreate.html">DMCreate</a></span><span class="p">(</span><span class="n">comm</span><span class="p">,</span><span class="o">&amp;</span><span class="n">dm</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DM/DMSetType.html">DMSetType</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="s">&quot;Typename&quot;</span><span class="p">);</span><span class="w">  </span><span class="c1">// for example, &quot;<a href="../manualpages/DMDA/DMDA.html">DMDA</a>&quot;</span>
</pre></div>
</div>
<p>Then <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMType.html">DMType</a></span></code> specific operations can be performed to provide information from which the specifics of the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> will be provided. For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMSetDimension.html">DMSetDimension</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDASetSizes.html">DMDASetSizes</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">));</span>
<span class="n"><a href="../manualpages/DMDA/DMDASetDof.html">DMDASetDof</a></span><span class="p">(</span><span class="n">dm</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">));</span>
<span class="n"><a href="../manualpages/DM/DMSetUp.html">DMSetUp</a></span><span class="p">(</span><span class="n">dm</span><span class="p">);</span>
</pre></div>
</div>
<p>We now very briefly introduce a few more <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMType.html">DMType</a></span></code>.</p>
</section>
<section id="dmstag-creating-vectors-for-staggered-grids">
<span id="sec-stag"></span><h3>DMSTAG - Creating vectors for staggered grids<a class="headerlink" href="#dmstag-creating-vectors-for-staggered-grids" title="Link to this heading">#</a></h3>
<p>For structured grids with staggered data (living on elements, faces, edges,
and/or vertices), the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMStag/DMSTAG.html">DMSTAG</a></span></code> object is available. It behaves much
like <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>.
See <a class="reference internal" href="dmstag.html#ch-stag"><span class="std std-ref">DMSTAG: Staggered, Structured Grid</span></a> for discussion of creating vectors with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMStag/DMSTAG.html">DMSTAG</a></span></code>.</p>
</section>
<section id="dmplex-creating-vectors-for-unstructured-grids">
<span id="sec-unstruct"></span><h3>DMPLEX - Creating vectors for unstructured grids<a class="headerlink" href="#dmplex-creating-vectors-for-unstructured-grids" title="Link to this heading">#</a></h3>
<p>See <a class="reference internal" href="dmplex.html#ch-unstructured"><span class="std std-ref">DMPlex: Unstructured Grids</span></a> for a discussion of creating vectors with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMPlex/DMPLEX.html">DMPLEX</a></span></code>.</p>
</section>
<section id="dmnetwork-creating-vectors-for-networks">
<span id="sec-network"></span><h3>DMNETWORK - Creating vectors for networks<a class="headerlink" href="#dmnetwork-creating-vectors-for-networks" title="Link to this heading">#</a></h3>
<p>See <a class="reference internal" href="dmnetwork.html#ch-network"><span class="std std-ref">Networks</span></a> for discussion of creating vectors with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMNetwork/DMNETWORK.html">DMNETWORK</a></span></code>.</p>
</section>
</section>
<section id="common-vector-functions-and-operations">
<h2>Common vector functions and operations<a class="headerlink" href="#common-vector-functions-and-operations" title="Link to this heading">#</a></h2>
<p>One can examine (print out) a vector with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecView.html">VecView</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span><span class="w"> </span><span class="n">v</span><span class="p">);</span>
</pre></div>
</div>
<p>To print the vector to the screen, one can use the viewer
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_STDOUT_WORLD.html">PETSC_VIEWER_STDOUT_WORLD</a></span></code>, which ensures that parallel vectors are
printed correctly to <code class="docutils notranslate"><span class="pre">stdout</span></code>. To display the vector in an X-window,
one can use the default X-windows viewer <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PETSC_VIEWER_DRAW_WORLD.html">PETSC_VIEWER_DRAW_WORLD</a></span></code>, or
one can create a viewer with the routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewerDrawOpen.html">PetscViewerDrawOpen</a>()</span></code>. A
variety of viewers are discussed further in
<a class="reference internal" href="other.html#sec-viewers"><span class="std std-ref">Viewers: Looking at PETSc Objects</span></a>.</p>
<p>To create a new vector of the same format and parallel layout as an existing vector,
use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</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">old</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">new</span><span class="p">);</span>
</pre></div>
</div>
<p>To create several new vectors of the same format as an existing vector,
use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecDuplicateVecs.html">VecDuplicateVecs</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">old</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">**</span><span class="n">new</span><span class="p">);</span>
</pre></div>
</div>
<p>This routine creates an array of pointers to vectors. The two routines
are useful because they allow one to write library code that does
not depend on the particular format of the vectors being used. Instead,
the subroutines can automatically create work vectors based on
the specified existing vector.</p>
<p>When a vector is no longer needed, it should be destroyed with the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecDestroy.html">VecDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>To destroy an array of vectors, use the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecDestroyVecs.html">VecDestroyVecs</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">**</span><span class="n">vecs</span><span class="p">);</span>
</pre></div>
</div>
<p>It is also possible to create vectors that use an array the user provides rather than having PETSc internally allocate the array space. Such
vectors can be created with the routines such as</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreateSeqWithArray.html">VecCreateSeqWithArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_SELF.html">PETSC_COMM_SELF</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">bs</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">V</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreateMPIWithArray.html">VecCreateMPIWithArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">bs</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">V</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreateMPICUDAWithArray.html">VecCreateMPICUDAWithArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">bs</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">V</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre">array</span></code> pointer should be a GPU memory location for GPU vectors.</p>
<p>Note that here, one must provide the value <code class="docutils notranslate"><span class="pre">n</span></code>; it cannot be
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span></code> and the user is responsible for providing enough space
in the array; <code class="docutils notranslate"><span class="pre">n*sizeof(<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a>)</span></code>.</p>
</section>
<section id="assembling-putting-values-in-vectors">
<h2>Assembling (putting values in) vectors<a class="headerlink" href="#assembling-putting-values-in-vectors" title="Link to this heading">#</a></h2>
<p>One can assign a single value to all components of a vector with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSet.html">VecSet</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">value</span><span class="p">);</span>
</pre></div>
</div>
<p>Assigning values to individual vector components is more
complicated to make it possible to write efficient parallel
code. Assigning a set of components on a CPU is a two-step process: one first
calls</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSetValues.html">VecSetValues</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">indices</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">values</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">);</span>
</pre></div>
</div>
<p>any number of times on any or all of the processes. The argument <code class="docutils notranslate"><span class="pre">n</span></code>
gives the number of components being set in this insertion. The integer
array <code class="docutils notranslate"><span class="pre">indices</span></code> contains the <em>global component indices</em>, and
<code class="docutils notranslate"><span class="pre">values</span></code> is the array of values to be inserted at those global component index locations. Any process can set
any vector components; PETSc ensures that they are automatically
stored in the correct location. Once all of the values have been
inserted with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValues.html">VecSetValues</a>()</span></code>, one must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecAssemblyBegin.html">VecAssemblyBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>followed by</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecAssemblyEnd.html">VecAssemblyEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">);</span>
</pre></div>
</div>
<p>to perform any needed message passing of nonlocal components. In order
to allow the overlap of communication and calculation, the user’s code
can perform any series of other actions between these two calls while
the messages are in transition.</p>
<p>Example usage of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValues.html">VecSetValues</a>()</span></code> may be found in
<a href="../src/vec/vec/tutorials/ex2.c.html">src/vec/vec/tutorials/ex2.c</a>
or <a href="../src/vec/vec/tutorials/ex2f.F90.html">src/vec/vec/tutorials/exf.F90</a>.</p>
<p>Rather than inserting elements in a vector, one may wish to add
values. This process is also done with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSetValues.html">VecSetValues</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">indices</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">values</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Again, one must call the assembly routines <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAssemblyBegin.html">VecAssemblyBegin</a>()</span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAssemblyEnd.html">VecAssemblyEnd</a>()</span></code> after all of the values have been added. Note that
addition and insertion calls to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValues.html">VecSetValues</a>()</span></code> <em>cannot</em> be mixed.
Instead, one must add and insert vector elements in phases, with
intervening calls to the assembly routines. This phased assembly
procedure overcomes the nondeterministic behavior that would occur if
two different processes generated values for the same location, with one
process adding while the other is inserting its value. (In this case, the
addition and insertion actions could be performed in either order, thus
resulting in different values at the particular location. Since PETSc
does not allow the simultaneous use of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code> and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code> this nondeterministic behavior will not occur in PETSc.)</p>
<p>You can call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGetValues.html">VecGetValues</a>()</span></code> to pull local values from a vector (but
not off-process values).</p>
<p>For vectors obtained with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a>()</span></code>, one can use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValuesLocal.html">VecSetValuesLocal</a>()</span></code> to set values into
a global vector but using the local (ghosted) vector indexing of the vector entries. See also <a class="reference internal" href="#sec-islocaltoglobalmap"><span class="std std-ref">Local to global mappings</span></a>
that allows one to provide arbitrary local-to-global mapping when not working with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>.</p>
<p>It is also possible to interact directly with the arrays that the vector values are stored
in. The routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a>()</span></code> returns a pointer to the elements local to
the process:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</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">v</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">array</span><span class="p">);</span>
</pre></div>
</div>
<p>When access to the array is no longer needed, the user should call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</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">v</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">array</span><span class="p">);</span>
</pre></div>
</div>
<p>If the values do not need to be modified, the routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetArrayRead.html">VecGetArrayRead</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">v</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">array</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecRestoreArrayRead.html">VecRestoreArrayRead</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">v</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">array</span><span class="p">);</span>
</pre></div>
</div>
<p>should be used instead.</p>
<div class="admonition-listing-a-href-petsc-doc-out-root-placeholder-src-snes-tutorials-ex1-c-html-snes-tutorial-src-snes-tutorials-ex1-c-a admonition">
<p class="admonition-title">Listing: <a href="../src/snes/tutorials/ex1.c.html">SNES Tutorial src/snes/tutorials/ex1.c</a></p>
<div class="highlight-c notranslate" id="snesex1"><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">FormFunction1</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">       </span><span class="o">*</span><span class="n">ff</span><span class="p">;</span>

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

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

<span class="w">  </span><span class="cm">/* Restore vectors */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArrayRead.html">VecRestoreArrayRead</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
</pre></div>
</div>
</div>
<p>Minor differences exist in the Fortran interface for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a>()</span></code>
and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a>()</span></code>, as discussed in
<a class="reference internal" href="fortran.html#sec-fortranarrays"><span class="std std-ref">Output Arrays from PETSc functions</span></a>. It is important to note that
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecRestoreArray.html">VecRestoreArray</a>()</span></code> do <em>not</em> copy the vector
elements; they merely give users direct access to the vector elements.
Thus, these routines require essentially no time to call and can be used
efficiently.</p>
<p>For GPU vectors, one can access either the values on the CPU as described above or one
can call, for example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCUDAGetArray.html">VecCUDAGetArray</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">v</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">array</span><span class="p">);</span>
</pre></div>
</div>
<div class="admonition-listing-a-href-petsc-doc-out-root-placeholder-src-snes-tutorials-ex47cu-cu-html-snes-tutorial-src-snes-tutorials-ex47cu-cu-a admonition">
<p class="admonition-title">Listing: <a href="../src/snes/tutorials/ex47cu.cu.html">SNES Tutorial src/snes/tutorials/ex47cu.cu</a></p>
<div class="highlight-c notranslate" id="snesex47"><div class="highlight"><pre><span></span><span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecCUDAGetArrayRead.html">VecCUDAGetArrayRead</a></span><span class="p">(</span><span class="n">xlocal</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xarray</span><span class="p">));</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecCUDAGetArrayWrite.html">VecCUDAGetArrayWrite</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">farray</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">rank</span><span class="p">)</span><span class="w"> </span><span class="n">xstartshift</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="k">else</span><span class="w"> </span><span class="n">xstartshift</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="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">rank</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">size</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="n">xendshift</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="k">else</span><span class="w"> </span><span class="n">xendshift</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="w">    </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/VecGetOwnershipRange.html">VecGetOwnershipRange</a></span><span class="p">(</span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">fstart</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/Vec/VecGetLocalSize.html">VecGetLocalSize</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">lsize</span><span class="p">));</span>
<span class="w">    </span><span class="c1">// clang-format off</span>
<span class="w">    </span><span class="n">try</span><span class="w"> </span><span class="p">{</span>
<span class="w">      </span><span class="n">thrust</span><span class="o">::</span><span class="n">for_each</span><span class="p">(</span>
<span class="w">        </span><span class="n">thrust</span><span class="o">::</span><span class="n">make_zip_iterator</span><span class="p">(</span>
<span class="w">          </span><span class="n">thrust</span><span class="o">::</span><span class="n">make_tuple</span><span class="p">(</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">farray</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">xarray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xstartshift</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">xarray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xstartshift</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">xarray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">xstartshift</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">counting_iterator</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span><span class="p">(</span><span class="n">fstart</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">constant_iterator</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span><span class="p">(</span><span class="n">Mx</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">constant_iterator</span><span class="o">&lt;</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">hx</span><span class="p">))),</span>
<span class="w">        </span><span class="n">thrust</span><span class="o">::</span><span class="n">make_zip_iterator</span><span class="p">(</span>
<span class="w">          </span><span class="n">thrust</span><span class="o">::</span><span class="n">make_tuple</span><span class="p">(</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">farray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">lsize</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">xarray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">lsize</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">xendshift</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">xarray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">lsize</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">xendshift</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">device_ptr</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">xarray</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">lsize</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">xendshift</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">counting_iterator</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span><span class="p">(</span><span class="n">fstart</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">lsize</span><span class="p">,</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">constant_iterator</span><span class="o">&lt;</span><span class="kt">int</span><span class="o">&gt;</span><span class="p">(</span><span class="n">Mx</span><span class="p">),</span>
<span class="w">            </span><span class="n">thrust</span><span class="o">::</span><span class="n">constant_iterator</span><span class="o">&lt;</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">&gt;</span><span class="p">(</span><span class="n">hx</span><span class="p">))),</span>
<span class="w">        </span><span class="n">ApplyStencil</span><span class="p">());</span>
<span class="w">    </span><span class="p">}</span>
</pre></div>
</div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetArrayAndMemType.html">VecGetArrayAndMemType</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">v</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">array</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscMemType.html">PetscMemType</a></span><span class="w"> </span><span class="o">*</span><span class="n">mtype</span><span class="p">);</span>
</pre></div>
</div>
<p>which, in the first case, returns a GPU memory address and, in the second case, returns either a CPU or GPU memory
address depending on the type of the vector. One can then launch a GPU kernel function that accesses the
vector’s memory for usage with GPUs. When computing on GPUs, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValues.html">VecSetValues</a>()</span></code> is not used! One always accesses the vector’s arrays and passes them
to the GPU code.</p>
<p>It can also be convenient to treat the vector entries as a Kokkos view. One first creates Kokkos vectors and then calls</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetKokkosView.html">VecGetKokkosView</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">v</span><span class="p">,</span><span class="w"> </span><span class="n">Kokkos</span><span class="o">::</span><span class="n">View</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">,</span><span class="n">MemorySpace</span><span class="o">&gt;</span><span class="w"> </span><span class="o">*</span><span class="n">kv</span><span class="p">)</span>
</pre></div>
</div>
<p>to set or access the vector entries.</p>
<p>Of course, to provide the correct values to a vector, one must know what parts of the vector are owned by each MPI process.
For parallel vectors, either CPU or GPU-based, it is possible to determine a process’s local range with the
routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetOwnershipRange.html">VecGetOwnershipRange</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">vec</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">start</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">end</span><span class="p">);</span>
</pre></div>
</div>
<p>The argument <code class="docutils notranslate"><span class="pre">start</span></code> indicates the first component owned by the local
process, while <code class="docutils notranslate"><span class="pre">end</span></code> specifies <em>one more than</em> the last owned by the
local process. This command is useful, for instance, in assembling
parallel vectors.</p>
<p>If the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> was obtained from a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a>()</span></code>, then the range values are determined by the specific <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>.
If the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> was created directly, the range values are determined by the local size passed to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetSizes.html">VecSetSizes</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecCreateMPI.html">VecCreateMPI</a>()</span></code>.
If <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PETSC_DECIDE.html">PETSC_DECIDE</a></span></code> was passed as the local size, then the vector uses default values for the range using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscSplitOwnership.html">PetscSplitOwnership</a>()</span></code>.
For certain <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>, it is better to use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> specific routines, such as <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAGetGhostCorners.html">DMDAGetGhostCorners</a>()</span></code>, to determine
the local values in the vector.</p>
<p>Very occasionally, all MPI processes need to know all the range values, these can be obtained with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetOwnershipRanges.html">VecGetOwnershipRanges</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">vec</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">range</span><span class="p">[]);</span>
</pre></div>
</div>
<p>The number of elements stored locally can be accessed with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetLocalSize.html">VecGetLocalSize</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">v</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">size</span><span class="p">);</span>
</pre></div>
</div>
<p>The global vector length can be determined by</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGetSize.html">VecGetSize</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">v</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">size</span><span class="p">);</span>
</pre></div>
</div>
<section id="dmda-setting-vector-values">
<span id="sec-struct-set"></span><h3>DMDA - Setting vector values<a class="headerlink" href="#dmda-setting-vector-values" title="Link to this heading">#</a></h3>
<p>PETSc provides an easy way to set values into the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> vectors and
access them using the natural grid indexing. This is done with the
routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
<span class="p">...</span><span class="w"> </span><span class="n">use</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="n">indexing</span><span class="w"> </span><span class="n">it</span><span class="w"> </span><span class="n">with</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">or</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="n">dimensions</span><span class="w"> </span><span class="p">...</span>
<span class="p">...</span><span class="w"> </span><span class="n">depending</span><span class="w"> </span><span class="n">on</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">dimension</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span><span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayRead.html">DMDAVecGetArrayRead</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
<span class="p">...</span><span class="w"> </span><span class="n">use</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="n">indexing</span><span class="w"> </span><span class="n">it</span><span class="w"> </span><span class="n">with</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">or</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="n">dimensions</span><span class="w"> </span><span class="p">...</span>
<span class="p">...</span><span class="w"> </span><span class="n">depending</span><span class="w"> </span><span class="n">on</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">dimension</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span><span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">array</span></code> is a multidimensional C array with the same dimension as <code class="docutils notranslate"><span class="pre">da</span></code>, and</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayDOF.html">DMDAVecGetArrayDOF</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
<span class="p">...</span><span class="w"> </span><span class="n">use</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="n">indexing</span><span class="w"> </span><span class="n">it</span><span class="w"> </span><span class="n">with</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">or</span><span class="w"> </span><span class="mi">4</span><span class="w"> </span><span class="n">dimensions</span><span class="w"> </span><span class="p">...</span>
<span class="p">...</span><span class="w"> </span><span class="n">depending</span><span class="w"> </span><span class="n">on</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">dimension</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span><span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayDOF.html">DMDAVecRestoreArrayDOF</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayDOFRead.html">DMDAVecGetArrayDOFRead</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
<span class="p">...</span><span class="w"> </span><span class="n">use</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="n">indexing</span><span class="w"> </span><span class="n">it</span><span class="w"> </span><span class="n">with</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">or</span><span class="w"> </span><span class="mi">4</span><span class="w"> </span><span class="n">dimensions</span><span class="w"> </span><span class="p">...</span>
<span class="p">...</span><span class="w"> </span><span class="n">depending</span><span class="w"> </span><span class="n">on</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">dimension</span><span class="w"> </span><span class="n">of</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span><span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayDOFRead.html">DMDAVecRestoreArrayDOFRead</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">array</span></code> is a multidimensional C array with one more dimension than
<code class="docutils notranslate"><span class="pre">da</span></code>. The vector <code class="docutils notranslate"><span class="pre">l</span></code> can be either a global vector or a local
vector. The <code class="docutils notranslate"><span class="pre">array</span></code> is accessed using the usual <em>global</em> indexing on
the entire grid, but the user may <em>only</em> refer to this array’s local and ghost
entries as all other entries are undefined. For example,
for a scalar problem in two dimensions, one could use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">**</span><span class="n">f</span><span class="p">,</span><span class="o">**</span><span class="n">u</span><span class="p">;</span>
<span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecGetArrayRead.html">DMDAVecGetArrayRead</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">local</span><span class="p">,</span><span class="o">&amp;</span><span class="n">u</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">global</span><span class="p">,</span><span class="o">&amp;</span><span class="n">f</span><span class="p">);</span>
<span class="p">...</span>
<span class="w">  </span><span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">u</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="p">...</span>
<span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">local</span><span class="p">,</span><span class="o">&amp;</span><span class="n">u</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">global</span><span class="p">,</span><span class="o">&amp;</span><span class="n">f</span><span class="p">);</span>
</pre></div>
</div>
<div class="admonition-listing-a-href-petsc-doc-out-root-placeholder-src-snes-tutorials-ex3-c-html-snes-tutorial-src-snes-tutorials-ex3-c-a admonition">
<p class="admonition-title">Listing: <a href="../src/snes/tutorials/ex3.c.html">SNES Tutorial src/snes/tutorials/ex3.c</a></p>
<div class="highlight-c notranslate" id="snesex3"><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">FormFunction</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w">    </span><span class="o">*</span><span class="n">user</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w">                 </span><span class="n">da</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">da</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">       </span><span class="o">*</span><span class="n">ff</span><span class="p">,</span><span class="w"> </span><span class="n">d</span><span class="p">;</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">xx</span><span class="p">,</span><span class="w"> </span><span class="o">*</span><span class="n">FF</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w">           </span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="n">xs</span><span class="p">,</span><span class="w"> </span><span class="n">xm</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">                </span><span class="n">xlocal</span><span class="p">;</span>

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

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

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

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

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

<span class="w">  </span><span class="cm">/*</span>
<span class="cm">     Restore vectors</span>
<span class="cm">  */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">xlocal</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">xx</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">f</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ff</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArrayRead.html">DMDAVecRestoreArrayRead</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">FF</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMRestoreLocalVector.html">DMRestoreLocalVector</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xlocal</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
</pre></div>
</div>
</div>
<p>The recommended approach for multi-component PDEs is to declare a
<code class="docutils notranslate"><span class="pre">struct</span></code> representing the fields defined at each node of the grid,
e.g.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">u</span><span class="p">,</span><span class="n">v</span><span class="p">,</span><span class="n">omega</span><span class="p">,</span><span class="n">temperature</span><span class="p">;</span>
<span class="p">}</span><span class="w"> </span><span class="n">Node</span><span class="p">;</span>
</pre></div>
</div>
<p>and write the residual evaluation using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Node</span><span class="w"> </span><span class="o">**</span><span class="n">f</span><span class="p">,</span><span class="o">**</span><span class="n">u</span><span class="p">;</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">local</span><span class="p">,</span><span class="o">&amp;</span><span class="n">u</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">global</span><span class="p">,</span><span class="o">&amp;</span><span class="n">f</span><span class="p">);</span>
<span class="w"> </span><span class="p">...</span>
<span class="w">    </span><span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">].</span><span class="n">omega</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">...</span>
<span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">local</span><span class="p">,</span><span class="o">&amp;</span><span class="n">u</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreArray.html">DMDAVecRestoreArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">global</span><span class="p">,</span><span class="o">&amp;</span><span class="n">f</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAVecGetArray.html">DMDAVecGetArray</a></span></code> routines are also provided for GPU access with CUDA, HIP, and Kokkos. For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetKokkosOffsetView.html">DMDAVecGetKokkosOffsetView</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">vec</span><span class="p">,</span><span class="n">Kokkos</span><span class="o">::</span><span class="n">View</span><span class="o">&lt;</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="n">XX</span><span class="o">*</span><span class="p">,</span><span class="n">MemorySpace</span><span class="o">&gt;</span><span class="w"> </span><span class="o">*</span><span class="n">ov</span><span class="p">)</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">*XX*</span></code> can contain any number of <code class="docutils notranslate"><span class="pre">*</span></code>. This allows one to write very natural Kokkos multi-dimensional parallel for kernels
that act on the local portion of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> vectors.</p>
<div class="admonition-listing-a-href-petsc-doc-out-root-placeholder-src-snes-tutorials-ex3k-kokkos-cxx-html-snes-tutorial-src-snes-tutorials-ex3k-kokkos-cxx-a admonition" id="snes-ex3-kokkos">
<p class="admonition-title">Listing: <a href="../src/snes/tutorials/ex3k.kokkos.cxx.html">SNES Tutorial src/snes/tutorials/ex3k.kokkos.cxx</a></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">KokkosFunction</span><span class="p">(</span><span class="n"><a href="../manualpages/SNES/SNES.html">SNES</a></span><span class="w"> </span><span class="n">snes</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n">ApplicationCtx</span><span class="w">                  </span><span class="o">*</span><span class="n">user</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">ApplicationCtx</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">ctx</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w">                               </span><span class="n">da</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">da</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">                      </span><span class="n">d</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">M</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">                              </span><span class="n">xl</span><span class="p">;</span>
<span class="w">  </span><span class="n">PetscScalarKokkosOffsetView</span><span class="w">      </span><span class="n">R</span><span class="p">;</span>
<span class="w">  </span><span class="n">ConstPetscScalarKokkosOffsetView</span><span class="w"> </span><span class="n">X</span><span class="p">,</span><span class="w"> </span><span class="n">F</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGetLocalVector.html">DMGetLocalVector</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xl</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGlobalToLocal.html">DMGlobalToLocal</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n">xl</span><span class="p">));</span>
<span class="w">  </span><span class="n">d</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mf">1.0</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="p">(</span><span class="n">user</span><span class="o">-&gt;</span><span class="n">h</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">h</span><span class="p">);</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAGetInfo.html">DMDAGetInfo</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">M</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetKokkosOffsetView.html">DMDAVecGetKokkosOffsetView</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">xl</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="cm">/* read only */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n">DMDAVecGetKokkosOffsetViewWrite</span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">R</span><span class="p">));</span><span class="w">  </span><span class="cm">/* write only */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecGetKokkosOffsetView.html">DMDAVecGetKokkosOffsetView</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">F</span><span class="p">));</span><span class="w"> </span><span class="cm">/* read only */</span>
<span class="w">  </span><span class="n">Kokkos</span><span class="o">::</span><span class="n">parallel_for</span><span class="p">(</span>
<span class="w">    </span><span class="n">Kokkos</span><span class="o">::</span><span class="n">RangePolicy</span><span class="o">&lt;&gt;</span><span class="p">(</span><span class="n">R</span><span class="p">.</span><span class="n">begin</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span><span class="w"> </span><span class="n">R</span><span class="p">.</span><span class="n">end</span><span class="p">(</span><span class="mi">0</span><span class="p">)),</span><span class="w"> </span><span class="n">KOKKOS_LAMBDA</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">      </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">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">R</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span><span class="w">                                                 </span><span class="cm">/* left boundary */</span>
<span class="w">      </span><span class="k">else</span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">M</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="n">R</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mf">1.0</span><span class="p">;</span><span class="w">                                  </span><span class="cm">/* right boundary */</span>
<span class="w">      </span><span class="k">else</span><span class="w"> </span><span class="n">R</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="p">(</span><span class="n">X</span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">)</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mf">2.0</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="mi">1</span><span class="p">))</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">X</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">F</span><span class="p">(</span><span class="n">i</span><span class="p">);</span><span class="w"> </span><span class="cm">/* interior */</span>
<span class="w">    </span><span class="p">});</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreKokkosOffsetView.html">DMDAVecRestoreKokkosOffsetView</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">xl</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">X</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n">DMDAVecRestoreKokkosOffsetViewWrite</span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">R</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMDA/DMDAVecRestoreKokkosOffsetView.html">DMDAVecRestoreKokkosOffsetView</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="n">user</span><span class="o">-&gt;</span><span class="n">F</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">F</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMRestoreLocalVector.html">DMRestoreLocalVector</a></span><span class="p">(</span><span class="n">da</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">xl</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
</pre></div>
</div>
</div>
<p>The global indices of the lower left corner of the local portion of vectors obtained from <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>
as well as the local array size can be obtained with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDAGetCorners.html">DMDAGetCorners</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">z</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">m</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">p</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DMDA/DMDAGetGhostCorners.html">DMDAGetGhostCorners</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">z</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">m</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">p</span><span class="p">);</span>
</pre></div>
</div>
<p>These values can then be used as loop bounds for local function evaluations as demonstrated in the function examples above.</p>
<p>The first version excludes ghost points, while the second
includes them. The routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAGetGhostCorners.html">DMDAGetGhostCorners</a>()</span></code> deals with the fact
that subarrays along boundaries of the problem domain have ghost points
only on their interior edges, but not on their boundary edges.</p>
<p>When either type of stencil is used, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_STAR</a></span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_BOX</a></span></code>, the local vectors (with the ghost points)
represent rectangular arrays, including the extra corner elements in the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_STAR</a></span></code> case. This configuration provides simple access to
the elements by employing two- (or three–) dimensional indexing. The
only difference between the two cases is that when <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDAStencilType.html">DMDA_STENCIL_STAR</a></span></code>
is used, the extra corner components are <em>not</em> scattered between the
processes and thus contain undefined values that should <em>not</em> be used.</p>
</section>
<section id="dmstag-setting-vector-values">
<span id="sec-stag-set"></span><h3>DMSTAG - Setting vector values<a class="headerlink" href="#dmstag-setting-vector-values" title="Link to this heading">#</a></h3>
<p>For structured grids with staggered data (living on elements, faces, edges,
and/or vertices), the <code class="docutils notranslate"><span class="pre">DMStag</span></code> object is available. It behaves
like <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>; see the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMStag/DMSTAG.html">DMSTAG</a></span></code> manual page for more information.</p>
<div class="admonition-listing-a-href-petsc-doc-out-root-placeholder-src-dm-impls-stag-tutorials-ex6-c-html-snes-tutorial-src-dm-impls-stag-tutorials-ex6-c-a admonition">
<p class="admonition-title">Listing: <a href="../src/dm/impls/stag/tutorials/ex6.c.html">SNES Tutorial src/dm/impls/stag/tutorials/ex6.c</a></p>
<div class="highlight-c notranslate" id="stagex6"><div class="highlight"><pre><span></span><span class="k">static</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">UpdateVelocity_2d</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">Ctx</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">buoyancy</span><span class="p">)</span>
<span class="p">{</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">                  </span><span class="n">velocity_local</span><span class="p">,</span><span class="w"> </span><span class="n">stress_local</span><span class="p">,</span><span class="w"> </span><span class="n">buoyancy_local</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">ex</span><span class="p">,</span><span class="w"> </span><span class="n">ey</span><span class="p">,</span><span class="w"> </span><span class="n">startx</span><span class="p">,</span><span class="w"> </span><span class="n">starty</span><span class="p">,</span><span class="w"> </span><span class="n">nx</span><span class="p">,</span><span class="w"> </span><span class="n">ny</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">slot_coord_next</span><span class="p">,</span><span class="w"> </span><span class="n">slot_coord_element</span><span class="p">,</span><span class="w"> </span><span class="n">slot_coord_prev</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">slot_vx_left</span><span class="p">,</span><span class="w"> </span><span class="n">slot_vy_down</span><span class="p">,</span><span class="w"> </span><span class="n">slot_buoyancy_down</span><span class="p">,</span><span class="w"> </span><span class="n">slot_buoyancy_left</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">slot_txx</span><span class="p">,</span><span class="w"> </span><span class="n">slot_tyy</span><span class="p">,</span><span class="w"> </span><span class="n">slot_txy_downleft</span><span class="p">,</span><span class="w"> </span><span class="n">slot_txy_downright</span><span class="p">,</span><span class="w"> </span><span class="n">slot_txy_upleft</span><span class="p">;</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">  </span><span class="o">**</span><span class="n">arr_coord_x</span><span class="p">,</span><span class="w"> </span><span class="o">**</span><span class="n">arr_coord_y</span><span class="p">;</span>
<span class="w">  </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">***</span><span class="n">arr_stress</span><span class="p">,</span><span class="w"> </span><span class="o">***</span><span class="n">arr_buoyancy</span><span class="p">;</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w">       </span><span class="o">***</span><span class="n">arr_velocity</span><span class="p">;</span>

<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBeginUser.html">PetscFunctionBeginUser</a></span><span class="p">;</span>
<span class="w">  </span><span class="cm">/* Prepare direct access to buoyancy data */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_buoyancy</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_LEFT</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="o">&amp;</span><span class="n">slot_buoyancy_left</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/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_buoyancy</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_DOWN</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="o">&amp;</span><span class="n">slot_buoyancy_down</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGetLocalVector.html">DMGetLocalVector</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_buoyancy</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">buoyancy_local</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGlobalToLocal.html">DMGlobalToLocal</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_buoyancy</span><span class="p">,</span><span class="w"> </span><span class="n">buoyancy</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n">buoyancy_local</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/DMStag/DMStagVecGetArrayRead.html">DMStagVecGetArrayRead</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_buoyancy</span><span class="p">,</span><span class="w"> </span><span class="n">buoyancy_local</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">arr_buoyancy</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* Prepare read-only access to stress data */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_ELEMENT</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="o">&amp;</span><span class="n">slot_txx</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/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_ELEMENT</a></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">slot_tyy</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/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_UP_LEFT</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="o">&amp;</span><span class="n">slot_txy_upleft</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/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_DOWN_LEFT</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="o">&amp;</span><span class="n">slot_txy_downleft</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/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_DOWN_RIGHT</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="o">&amp;</span><span class="n">slot_txy_downright</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGetLocalVector.html">DMGetLocalVector</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">stress_local</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGlobalToLocal.html">DMGlobalToLocal</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n">stress</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n">stress_local</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/DMStag/DMStagVecGetArrayRead.html">DMStagVecGetArrayRead</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_stress</span><span class="p">,</span><span class="w"> </span><span class="n">stress_local</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">arr_stress</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* Prepare read-write access to velocity data */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_LEFT</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="o">&amp;</span><span class="n">slot_vx_left</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/DMStag/DMStagGetLocationSlot.html">DMStagGetLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_DOWN</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="o">&amp;</span><span class="n">slot_vy_down</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGetLocalVector.html">DMGetLocalVector</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">velocity_local</span><span class="p">));</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DMGlobalToLocal.html">DMGlobalToLocal</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n">velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n">velocity_local</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/DMStag/DMStagVecGetArray.html">DMStagVecGetArray</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n">velocity_local</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">arr_velocity</span><span class="p">));</span>

<span class="w">  </span><span class="cm">/* Prepare read-only access to coordinate data */</span>
<span class="w">  </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DMStag/DMStagGetProductCoordinateLocationSlot.html">DMStagGetProductCoordinateLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_LEFT</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">slot_coord_prev</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/DMStag/DMStagGetProductCoordinateLocationSlot.html">DMStagGetProductCoordinateLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_RIGHT</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">slot_coord_next</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/DMStag/DMStagGetProductCoordinateLocationSlot.html">DMStagGetProductCoordinateLocationSlot</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/DMStag/DMStagStencilLocation.html">DMSTAG_ELEMENT</a></span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">slot_coord_element</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/DMStag/DMStagGetProductCoordinateArrays.html">DMStagGetProductCoordinateArrays</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">arr_coord_x</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="o">&amp;</span><span class="n">arr_coord_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="cm">/* Iterate over interior of the domain, updating the velocities */</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/DMStag/DMStagGetCorners.html">DMStagGetCorners</a></span><span class="p">(</span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dm_velocity</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">startx</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">starty</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">nx</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">ny</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">,</span><span class="w"> </span><span class="nb">NULL</span><span class="p">));</span>
<span class="w">  </span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">ey</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">starty</span><span class="p">;</span><span class="w"> </span><span class="n">ey</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">starty</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">ny</span><span class="p">;</span><span class="w"> </span><span class="o">++</span><span class="n">ey</span><span class="p">)</span><span class="w"> </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">ex</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">startx</span><span class="p">;</span><span class="w"> </span><span class="n">ex</span><span class="w"> </span><span class="o">&lt;</span><span class="w"> </span><span class="n">startx</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">nx</span><span class="p">;</span><span class="w"> </span><span class="o">++</span><span class="n">ex</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">      </span><span class="cm">/* Update y-velocity */</span>
<span class="w">      </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">ey</span><span class="w"> </span><span class="o">&gt;</span><span class="w"> </span><span class="mi">0</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w">        </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">dx</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">arr_coord_x</span><span class="p">[</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_coord_next</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">arr_coord_x</span><span class="p">[</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_coord_prev</span><span class="p">];</span>
<span class="w">        </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">dy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">arr_coord_y</span><span class="p">[</span><span class="n">ey</span><span class="p">][</span><span class="n">slot_coord_element</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">arr_coord_y</span><span class="p">[</span><span class="n">ey</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">][</span><span class="n">slot_coord_element</span><span class="p">];</span>
<span class="w">        </span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">B</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="n">arr_buoyancy</span><span class="p">[</span><span class="n">ey</span><span class="p">][</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_buoyancy_down</span><span class="p">];</span>

<span class="w">        </span><span class="n">arr_velocity</span><span class="p">[</span><span class="n">ey</span><span class="p">][</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_vy_down</span><span class="p">]</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span><span class="n">B</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="o">-&gt;</span><span class="n">dt</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="p">((</span><span class="n">arr_stress</span><span class="p">[</span><span class="n">ey</span><span class="p">][</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_txy_downright</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">arr_stress</span><span class="p">[</span><span class="n">ey</span><span class="p">][</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_txy_downleft</span><span class="p">])</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">dx</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="p">(</span><span class="n">arr_stress</span><span class="p">[</span><span class="n">ey</span><span class="p">][</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_tyy</span><span class="p">]</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">arr_stress</span><span class="p">[</span><span class="n">ey</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">][</span><span class="n">ex</span><span class="p">][</span><span class="n">slot_tyy</span><span class="p">])</span><span class="w"> </span><span class="o">/</span><span class="w"> </span><span class="n">dy</span><span class="p">);</span>
<span class="w">      </span><span class="p">}</span>

<span class="w">      </span><span class="cm">/* Update x-velocity */</span>
</pre></div>
</div>
</div>
</section>
<section id="dmplex-setting-vector-values">
<span id="sec-unstruct-set"></span><h3>DMPLEX - Setting vector values<a class="headerlink" href="#dmplex-setting-vector-values" title="Link to this heading">#</a></h3>
<p>See <a class="reference internal" href="dmplex.html#ch-unstructured"><span class="std std-ref">DMPlex: Unstructured Grids</span></a> for a discussion on setting vector values with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMPlex/DMPLEX.html">DMPLEX</a></span></code>.</p>
</section>
<section id="dmnetwork-setting-vector-values">
<span id="sec-network-set"></span><h3>DMNETWORK - Setting vector values<a class="headerlink" href="#dmnetwork-setting-vector-values" title="Link to this heading">#</a></h3>
<p>See <a class="reference internal" href="dmnetwork.html#ch-network"><span class="std std-ref">Networks</span></a> for a discussion on setting vector values with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMNetwork/DMNETWORK.html">DMNETWORK</a></span></code>.</p>
</section>
</section>
<section id="basic-vector-operations">
<span id="sec-vecbasic"></span><h2>Basic Vector Operations<a class="headerlink" href="#basic-vector-operations" title="Link to this heading">#</a></h2>
<div class="docutils container" id="fig-vectorops">
<table class="table" id="id1">
<caption><span class="caption-number">Table 2 </span><span class="caption-text">PETSc Vector Operations</span><a class="headerlink" href="#id1" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p><strong>Function Name</strong></p></th>
<th class="head"><p><strong>Operation</strong></p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAXPY.html">VecAXPY</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">a,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x);</span></code></p></td>
<td><p><span class="math">\(y = y + a*x\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAYPX.html">VecAYPX</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">a,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x);</span></code></p></td>
<td><p><span class="math">\(y = x + a*y\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecWAXPY.html">VecWAXPY</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span>&#160; <span class="pre">w,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">a,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y);</span></code></p></td>
<td><p><span class="math">\(w = a*x + y\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAXPBY.html">VecAXPBY</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">a,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">b,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x);</span></code></p></td>
<td><p><span class="math">\(y = a*x + b*y\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAXPBYPCZ.html">VecAXPBYPCZ</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">z,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">a,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">b,</span>
<span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">c,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y);</span></code></p></td>
<td><p><span class="math">\(z = a*x + b*y + c*z\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScale.html">VecScale</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">a);</span></code></p></td>
<td><p><span class="math">\(x = a*x\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDot.html">VecDot</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y,</span> <span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r = \bar{x}^T*y\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecTDot.html">VecTDot</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y,</span> <span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r = x'*y\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecNorm.html">VecNorm</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Vec/NormType.html">NormType</a></span> <span class="pre">type,</span>&#160; <span class="pre"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r = ||x||_{type}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSum.html">VecSum</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r = \sum x_{i}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecCopy.html">VecCopy</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y);</span></code></p></td>
<td><p><span class="math">\(y = x\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSwap.html">VecSwap</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y);</span></code></p></td>
<td><p><span class="math">\(y = x\)</span> while
<span class="math">\(x = y\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecPointwiseMult.html">VecPointwiseMult</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">w,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y);</span></code></p></td>
<td><p><span class="math">\(w_{i} = x_{i}*y_{i}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecPointwiseDivide.html">VecPointwiseDivide</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">w,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y);</span></code></p></td>
<td><p><span class="math">\(w_{i} = x_{i}/y_{i}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMDot.html">VecMDot</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span> <span class="pre">n,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y[],<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r[i] = \bar{x}^T*y[i]\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMTDot.html">VecMTDot</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span> <span class="pre">n,<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y[],<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r[i] = x^T*y[i]\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMAXPY.html">VecMAXPY</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">y,<a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span> <span class="pre">n,</span> <span class="pre"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">*a,</span> <span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x[]);</span></code></p></td>
<td><p><span class="math">\(y = y + \sum_i a_{i}*x[i]\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMax.html">VecMax</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span> <span class="pre">*idx,</span> <span class="pre"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r = \max x_{i}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMin.html">VecMin</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,</span> <span class="pre"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span> <span class="pre">*idx,</span> <span class="pre"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span> <span class="pre">*r);</span></code></p></td>
<td><p><span class="math">\(r = \min x_{i}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecAbs.html">VecAbs</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x);</span></code></p></td>
<td><p><span class="math">\(x_i = |x_{i}|\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecReciprocal.html">VecReciprocal</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x);</span></code></p></td>
<td><p><span class="math">\(x_i = 1/x_{i}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecShift.html">VecShift</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">s);</span></code></p></td>
<td><p><span class="math">\(x_i = s + x_{i}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSet.html">VecSet</a>(<a href="../manualpages/Vec/Vec.html">Vec</a></span> <span class="pre">x,<a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span> <span class="pre">alpha);</span></code></p></td>
<td><p><span class="math">\(x_i = \alpha\)</span></p></td>
</tr>
</tbody>
</table>
</div>
<p>As the table lists, we have chosen certain
basic vector operations to support within the PETSc vector library.
These operations were selected because they often arise in application
codes. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/NormType.html">NormType</a></span></code> argument to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecNorm.html">VecNorm</a>()</span></code> is one of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/NORM_1.html">NORM_1</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/NORM_2.html">NORM_2</a></span></code>, or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/NORM_INFINITY.html">NORM_INFINITY</a></span></code>. The 1-norm is <span class="math">\(\sum_i |x_{i}|\)</span>,
the 2-norm is <span class="math">\(( \sum_{i} x_{i}^{2})^{1/2}\)</span> and the infinity norm
is <span class="math">\(\max_{i} |x_{i}|\)</span>.</p>
<p>In addition to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDot.html">VecDot</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMDot.html">VecMDot</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecNorm.html">VecNorm</a>()</span></code>, PETSc
provides split phase versions of this functionality that allow several independent
inner products and/or norms to share the same communication (thus
improving parallel efficiency). For example, one may have code such as</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecDot.html">VecDot</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">dot</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecMDot.html">VecMDot</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nv</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">dot</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecNorm.html">VecNorm</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_2.html">NORM_2</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">norm2</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecNorm.html">VecNorm</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_1.html">NORM_1</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">norm1</span><span class="p">);</span>
</pre></div>
</div>
<p>This code works fine, but it performs four separate parallel
communication operations. Instead, one can write</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecDotBegin.html">VecDotBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">dot</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecMDotBegin.html">VecMDotBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nv</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">dot</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecNormBegin.html">VecNormBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_2.html">NORM_2</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">norm2</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecNormBegin.html">VecNormBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_1.html">NORM_1</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">norm1</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecDotEnd.html">VecDotEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">dot</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecMDotEnd.html">VecMDotEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nv</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">dot</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecNormEnd.html">VecNormEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_2.html">NORM_2</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">norm2</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecNormEnd.html">VecNormEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/NORM_1.html">NORM_1</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="o">*</span><span class="n">norm1</span><span class="p">);</span>
</pre></div>
</div>
<p>With this code, the communication is delayed until the first call to
<code class="docutils notranslate"><span class="pre">VecxxxEnd()</span></code> at which a single MPI reduction is used to communicate
all the values. It is required that the calls to the
<code class="docutils notranslate"><span class="pre">VecxxxEnd()</span></code> are performed in the same order as the calls to the
<code class="docutils notranslate"><span class="pre">VecxxxBegin()</span></code>; however, if you mistakenly make the calls in the
wrong order, PETSc will generate an error informing you of this. There
are additional routines <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecTDotBegin.html">VecTDotBegin</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecTDotEnd.html">VecTDotEnd</a>()</span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMTDotBegin.html">VecMTDotBegin</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecMTDotEnd.html">VecMTDotEnd</a>()</span></code>.</p>
<p>For GPU vectors (like CUDA), the numerical computations will, by default, run on the GPU. Any
scalar output, like the result of a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDot.html">VecDot</a>()</span></code> are placed in CPU memory.</p>
</section>
<section id="local-global-vectors-and-communicating-between-vectors">
<span id="sec-localglobal"></span><h2>Local/global vectors and communicating between vectors<a class="headerlink" href="#local-global-vectors-and-communicating-between-vectors" title="Link to this heading">#</a></h2>
<p>Many PDE problems require ghost (or halo) values in each MPI process or even more general parallel communication
of vector values. These values are needed
to perform function evaluation on that MPI process. The exact structure of the ghost values needed
depends on the type of grid being used. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> provides a uniform API for communicating the needed
values. We introduce the concept in detail for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>.</p>
<p>Each <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> object defines the layout of two vectors: a distributed
global vector and a local vector that includes room for the appropriate
ghost points. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> object provides information about the size
and layout of these vectors. The user can create
vector objects that use the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> layout information with the
routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">g</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DM/DMCreateLocalVector.html">DMCreateLocalVector</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">l</span><span class="p">);</span>
</pre></div>
</div>
<p>These vectors will generally serve as the building blocks for local and
global PDE solutions, etc. If additional vectors with such layout
information are needed in a code, they can be obtained by duplicating
<code class="docutils notranslate"><span class="pre">l</span></code> or <code class="docutils notranslate"><span class="pre">g</span></code> via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicateVecs.html">VecDuplicateVecs</a>()</span></code>.</p>
<p>We emphasize that a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> provides the information needed to
communicate the ghost value information between processes. In most
cases, several different vectors can share the same communication
information (or, in other words, can share a given <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>). The design
of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> object makes this easy, as each <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> operation may
operate on vectors of the appropriate size, as obtained via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateLocalVector.html">DMCreateLocalVector</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a>()</span></code> or as produced
by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a>()</span></code>.</p>
<p>At certain stages of many applications, there is a need to work on a
local portion of the vector that includes the ghost points. This may be
done by scattering a global vector into its local parts by using the
two-stage commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMGlobalToLocalBegin.html">DMGlobalToLocalBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">g</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">iora</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DM/DMGlobalToLocalEnd.html">DMGlobalToLocalEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">g</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">iora</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">);</span>
</pre></div>
</div>
<p>which allows the overlap of communication and computation. Since the
global and local vectors, given by <code class="docutils notranslate"><span class="pre">g</span></code> and <code class="docutils notranslate"><span class="pre">l</span></code>, respectively, must
be compatible with the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, <code class="docutils notranslate"><span class="pre">da</span></code>, they should be
generated by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateLocalVector.html">DMCreateLocalVector</a>()</span></code>
(or be duplicates of such a vector obtained via <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a>()</span></code>). The
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span></code> can be <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code> among other possible values.</p>
<p>One can scatter the local vectors into the distributed global vector with the
command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMLocalToGlobal.html">DMLocalToGlobal</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">g</span><span class="p">);</span>
</pre></div>
</div>
<p>or the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMLocalToGlobalBegin.html">DMLocalToGlobalBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">g</span><span class="p">);</span>
<span class="cm">/* (Computation to overlap with communication) */</span>
<span class="n"><a href="../manualpages/DM/DMLocalToGlobalEnd.html">DMLocalToGlobalEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">g</span><span class="p">);</span>
</pre></div>
</div>
<p>In general this is used with an <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span></code> of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code>,
because if one wishes to insert values into the global vector, they
should access the global vector directly and put in the values.</p>
<p>A third type of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> scatter is from a local vector
(including ghost points that contain irrelevant values) to a local
vector with correct ghost point values. This scatter may be done with
the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMLocalToLocalBegin.html">DMLocalToLocalBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l1</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">iora</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l2</span><span class="p">);</span>
<span class="n"><a href="../manualpages/DM/DMLocalToLocalEnd.html">DMLocalToLocalEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l1</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n">iora</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">l2</span><span class="p">);</span>
</pre></div>
</div>
<p>Since both local vectors, <code class="docutils notranslate"><span class="pre">l1</span></code> and <code class="docutils notranslate"><span class="pre">l2</span></code>, must be compatible with <code class="docutils notranslate"><span class="pre">da</span></code>, they should be generated by
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateLocalVector.html">DMCreateLocalVector</a>()</span></code> (or be duplicates of such vectors obtained via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a>()</span></code>). The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span></code> can be either <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code>.</p>
<p>In most applications, the local ghosted vectors are only needed temporarily during
user “function evaluations”. PETSc provides an easy, light-weight
(requiring essentially no CPU time) way to temporarily obtain these work vectors and
return them when no longer needed. This is done with the
routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMGetLocalVector.html">DMGetLocalVector</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">l</span><span class="p">);</span>
<span class="p">...</span><span class="w"> </span><span class="n">use</span><span class="w"> </span><span class="n">the</span><span class="w"> </span><span class="n">local</span><span class="w"> </span><span class="n">vector</span><span class="w"> </span><span class="n">l</span><span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/DM/DMRestoreLocalVector.html">DMRestoreLocalVector</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">l</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="low-level-vector-communication">
<span id="sec-scatter"></span><h2>Low-level Vector Communication<a class="headerlink" href="#low-level-vector-communication" title="Link to this heading">#</a></h2>
<p>Most users of PETSc who can utilize a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> will not need to utilize the lower-level routines discussed in the rest of this section
and should skip ahead to <a class="reference internal" href="mat.html#ch-matrices"><span class="std std-ref">Matrices</span></a>.</p>
<p>To facilitate creating general vector scatters and gathers used, for example, in
updating ghost points for problems for which no <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> currently exists
PETSc employs the concept of an <em>index set</em>, via the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code> class. An
index set, a generalization of a set of integer indices, is
used to define scatters, gathers, and similar operations on vectors and
matrices. Much of the underlying code that implements <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMGlobalToLocal.html">DMGlobalToLocal</a></span></code> communication is built
on the infrastructure discussed below.</p>
<p>The following command creates an index set based on a list of integers:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISCreateGeneral.html">ISCreateGeneral</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">indices</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscCopyMode.html">PetscCopyMode</a></span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">is</span><span class="p">);</span>
</pre></div>
</div>
<p>When <code class="docutils notranslate"><span class="pre">mode</span></code> is <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscCopyMode.html">PETSC_COPY_VALUES</a></span></code>, this routine copies the <code class="docutils notranslate"><span class="pre">n</span></code>
indices passed to it by the integer array <code class="docutils notranslate"><span class="pre">indices</span></code>. Thus, the user
should be sure to free the integer array <code class="docutils notranslate"><span class="pre">indices</span></code> when it is no
longer needed, perhaps directly after the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISCreateGeneral.html">ISCreateGeneral</a>()</span></code>.
The communicator, <code class="docutils notranslate"><span class="pre">comm</span></code>, should include all processes
using the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code>.</p>
<p>Another standard index set is defined by a starting point (<code class="docutils notranslate"><span class="pre">first</span></code>)
and a stride (<code class="docutils notranslate"><span class="pre">step</span></code>), and can be created with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISCreateStride.html">ISCreateStride</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">first</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">step</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">is</span><span class="p">);</span>
</pre></div>
</div>
<p>The meaning of <code class="docutils notranslate"><span class="pre">n</span></code>, <code class="docutils notranslate"><span class="pre">first</span></code>, and <code class="docutils notranslate"><span class="pre">step</span></code> correspond to the MATLAB notation
<code class="docutils notranslate"><span class="pre">first:step:first+n*step</span></code>.</p>
<p>Index sets can be destroyed with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISDestroy.html">ISDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">&amp;</span><span class="n">is</span><span class="p">);</span>
</pre></div>
</div>
<p>On rare occasions, the user may need to access information directly from
an index set. Several commands assist in this process:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISGetSize.html">ISGetSize</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">is</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">size</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISStrideGetInfo.html">ISStrideGetInfo</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">is</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">first</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">stride</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISGetIndices.html">ISGetIndices</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">is</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">**</span><span class="n">indices</span><span class="p">);</span>
</pre></div>
</div>
<p>The function <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISGetIndices.html">ISGetIndices</a>()</span></code> returns a pointer to a list of the
indices in the index set. For certain index sets, this may be a
temporary array of indices created specifically for the call.
Thus, once the user finishes using the array of indices, the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISRestoreIndices.html">ISRestoreIndices</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">is</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">indices</span><span class="p">);</span>
</pre></div>
</div>
<p>should be called to ensure that the system can free the space it may
have used to generate the list of indices.</p>
<p>A blocked version of index sets can be created with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISCreateBlock.html">ISCreateBlock</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">bs</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">indices</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscCopyMode.html">PetscCopyMode</a></span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="o">*</span><span class="n">is</span><span class="p">);</span>
</pre></div>
</div>
<p>This version is used for defining operations in which each element of
the index set refers to a block of <code class="docutils notranslate"><span class="pre">bs</span></code> vector entries. Related
routines analogous to those described above exist as well, including
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISBlockGetIndices.html">ISBlockGetIndices</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISBlockGetSize.html">ISBlockGetSize</a>()</span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISBlockGetLocalSize.html">ISBlockGetLocalSize</a>()</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISGetBlockSize.html">ISGetBlockSize</a>()</span></code>.</p>
<p>Most PETSc applications use a particular <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> object to manage the communication details needed for their grids.
In some rare cases, however, codes need to directly set up their required communication patterns. This is done using
PETSc’s <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/PetscSF.html">PetscSF</a></span></code> (for more general data than vectors). One
can select any subset of the components of a vector to insert or add to
any subset of the components of another vector. We refer to these
operations as <em>generalized scatters</em>, though they are a
combination of scatters and gathers.</p>
<p>To copy selected components from one vector to another, one uses the
following set of commands:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">ix</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">iy</span><span class="p">,</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterDestroy.html">VecScatterDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>Here <code class="docutils notranslate"><span class="pre">ix</span></code> denotes the index set of the first vector, while <code class="docutils notranslate"><span class="pre">iy</span></code>
indicates the index set of the destination vector. The vectors can be
parallel or sequential. The only requirements are that the number of
entries in the index set of the first vector, <code class="docutils notranslate"><span class="pre">ix</span></code>, equals the number
in the destination index set, <code class="docutils notranslate"><span class="pre">iy</span></code>, and that the vectors be long
enough to contain all the indices referred to in the index sets. If both
<code class="docutils notranslate"><span class="pre">x</span></code> and <code class="docutils notranslate"><span class="pre">y</span></code> are parallel, their communicator must have the same set
of processes, but their process order can differ. The argument
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code> specifies that the vector elements will be inserted
into the specified locations of the destination vector, overwriting any
existing values. To add the components, rather than insert them, the
user should select the option <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code> instead of
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code>. One can also use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/MAX_VALUES.html">MAX_VALUES</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/MIN_VALUES.html">MIN_VALUES</a></span></code> to
replace the destination with the maximal or minimal of its current value and
the scattered values.</p>
<p>To perform a conventional gather operation, the user makes the
destination index set, <code class="docutils notranslate"><span class="pre">iy</span></code>, be a stride index set with a stride of
one. Similarly, a conventional scatter can be done with an initial
(sending) index set consisting of a stride. The scatter routines are
collective operations (i.e. all processes that own a parallel vector
<em>must</em> call the scatter routines). When scattering from a parallel
vector to sequential vectors, each process has its own sequential vector
that receives values from locations as indicated in its own index set.
Similarly, in scattering from sequential vectors to a parallel vector,
each process has its own sequential vector that contributes to
the parallel vector.</p>
<p><em>Caution</em>: When <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code> is used, if two different processes
contribute different values to the same component in a parallel vector,
either value may be inserted. When <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code> is used, the
correct sum is added to the correct location.</p>
<p>In some cases, one may wish to “undo” a scatter, that is, perform the
scatter backward, switching the roles of the sender and receiver. This
is done by using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">y</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Note that the roles of the first two arguments to these routines must be
swapped whenever the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span></code> option is used.</p>
<p>Once a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span></code> object has been created, it may be used with any
vectors that have the same parallel data layout. That is, one can
call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a>()</span></code> with different
vectors than used in the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a>()</span></code> as long as they
have the same parallel layout (the number of elements on each process are
the same). Usually, these “different” vectors would have been obtained
via calls to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a>()</span></code> from the original vectors used in the
call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a>()</span></code>.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGetValues.html">VecGetValues</a>()</span></code> can only access
local values from the vector. To get off-process values, the user should
create a new vector where the components will be stored and then
perform the appropriate vector scatter. For example, if one desires to
obtain the values of the 100th and 200th entries of a parallel vector,
<code class="docutils notranslate"><span class="pre">p</span></code>, one could use a code such as that below. In this example, the
values of the 100th and 200th components are placed in the array values.
In this example, each process now has the 100th and 200th component, but
obviously, each process could gather any elements it needed, or none by
creating an index set with no entries.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w">         </span><span class="n">p</span><span class="p">,</span><span class="w"> </span><span class="n">x</span><span class="p">;</span><span class="w">         </span><span class="cm">/* initial vector, destination vector */</span>
<span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w">  </span><span class="n">scatter</span><span class="p">;</span><span class="w">      </span><span class="cm">/* scatter context */</span>
<span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w">          </span><span class="n">from</span><span class="p">,</span><span class="w"> </span><span class="n">to</span><span class="p">;</span><span class="w">     </span><span class="cm">/* index sets that define the scatter */</span>
<span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">values</span><span class="p">;</span>
<span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w">    </span><span class="n">idx_from</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">100</span><span class="p">,</span><span class="mi">200</span><span class="p">},</span><span class="w"> </span><span class="n">idx_to</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span><span class="mi">0</span><span class="p">,</span><span class="mi">1</span><span class="p">};</span>

<span class="n"><a href="../manualpages/Vec/VecCreateSeq.html">VecCreateSeq</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_SELF.html">PETSC_COMM_SELF</a></span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="o">&amp;</span><span class="n">x</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISCreateGeneral.html">ISCreateGeneral</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_SELF.html">PETSC_COMM_SELF</a></span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="n">idx_from</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscCopyMode.html">PETSC_COPY_VALUES</a></span><span class="p">,</span><span class="o">&amp;</span><span class="n">from</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISCreateGeneral.html">ISCreateGeneral</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PETSC_COMM_SELF.html">PETSC_COMM_SELF</a></span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="n">idx_to</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscCopyMode.html">PETSC_COPY_VALUES</a></span><span class="p">,</span><span class="o">&amp;</span><span class="n">to</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterCreate.html">VecScatterCreate</a></span><span class="p">(</span><span class="n">p</span><span class="p">,</span><span class="n">from</span><span class="p">,</span><span class="n">x</span><span class="p">,</span><span class="n">to</span><span class="p">,</span><span class="o">&amp;</span><span class="n">scatter</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n">scatter</span><span class="p">,</span><span class="n">p</span><span class="p">,</span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n">scatter</span><span class="p">,</span><span class="n">p</span><span class="p">,</span><span class="n">x</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGetArray.html">VecGetArray</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="o">&amp;</span><span class="n">values</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISDestroy.html">ISDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">from</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISDestroy.html">ISDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">to</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterDestroy.html">VecScatterDestroy</a></span><span class="p">(</span><span class="o">&amp;</span><span class="n">scatter</span><span class="p">);</span>
</pre></div>
</div>
<p>The scatter comprises two stages to allow for the overlap of
communication and computation. The introduction of the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span></code>
context allows the communication patterns for the scatter to be computed
once and reused repeatedly. Generally, even setting up the
communication for a scatter requires communication; hence, it is best to
reuse such information when possible.</p>
<p>Scatters provide a very general method for managing the
communication of required ghost values for unstructured grid
computations. One scatters the global vector into a local “ghosted” work
vector, performs the computation on the local work vectors, and then
scatters back into the global solution vector. In the simplest case, this
may be written as</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">scatter</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">globalin</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">localin</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">scatter</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">globalin</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">localin</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="cm">/* For example, do local calculations from localin to localout */</span>
<span class="p">...</span>
<span class="n"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">scatter</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">localout</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">globalout</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/PetscSF/VecScatter.html">VecScatter</a></span><span class="w"> </span><span class="n">scatter</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">localout</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">globalout</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>In this case, the scatter is used in a way similar to the usage of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMGlobalToLocal.html">DMGlobalToLocal</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMLocalToGlobal.html">DMLocalToGlobal</a>()</span></code> discussed above.</p>
<section id="local-to-global-mappings">
<span id="sec-islocaltoglobalmap"></span><h3>Local to global mappings<a class="headerlink" href="#local-to-global-mappings" title="Link to this heading">#</a></h3>
<p>When working with a global representation of a vector
(usually on a vector obtained with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateGlobalVector.html">DMCreateGlobalVector</a>()</span></code>) and a local
representation of the same vector that includes ghost points required
for local computation (obtained with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateLocalVector.html">DMCreateLocalVector</a>()</span></code>). PETSc provides routines to help map indices from
a local numbering scheme to the PETSc global numbering scheme, recall their use above for the routine <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValuesLocal.html">VecSetValuesLocal</a>()</span></code> introduced above.
This is done via the following routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMappingCreate.html">ISLocalToGlobalMappingCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">bs</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="o">*</span><span class="w"> </span><span class="n">globalnum</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscCopyMode.html">PetscCopyMode</a></span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="o">*</span><span class="w"> </span><span class="n">ctx</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISLocalToGlobalMappingApply.html">ISLocalToGlobalMappingApply</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">in</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">out</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISLocalToGlobalMappingApplyIS.html">ISLocalToGlobalMappingApplyIS</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">isin</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="o">*</span><span class="w"> </span><span class="n">isout</span><span class="p">);</span>
<span class="n"><a href="../manualpages/IS/ISLocalToGlobalMappingDestroy.html">ISLocalToGlobalMappingDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>Here <code class="docutils notranslate"><span class="pre">N</span></code> denotes the number of local indices, <code class="docutils notranslate"><span class="pre">globalnum</span></code> contains
the global number of each local number, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span></code>
is the resulting PETSc object that contains the information needed to
apply the mapping with either <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISLocalToGlobalMappingApply.html">ISLocalToGlobalMappingApply</a>()</span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISLocalToGlobalMappingApplyIS.html">ISLocalToGlobalMappingApplyIS</a>()</span></code>.</p>
<p>Note that the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span></code> routines serve a different
purpose than the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> routines. In the former case, they provide a
mapping from a local numbering scheme (including ghost points) to a
global numbering scheme, while in the latter, they provide a mapping
between two global numbering schemes. Many applications may use
both <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span></code> routines. The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> routines
are first used to map from an application global ordering (that has no
relationship to parallel processing, etc.) to the PETSc ordering scheme
(where each process has a contiguous set of indices in the numbering).
Then, to perform function or Jacobian evaluations locally on
each process, one works with a local numbering scheme that includes
ghost points. The mapping from this local numbering scheme back to the
global PETSc numbering can be handled with the
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span></code> routines.</p>
<p>If one is given a list of block indices in a global numbering, the
routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/IS/ISGlobalToLocalMappingApplyBlock.html">ISGlobalToLocalMappingApplyBlock</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISGlobalToLocalMappingMode.html">ISGlobalToLocalMappingMode</a></span><span class="w"> </span><span class="n">type</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nin</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">idxin</span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">nout</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">idxout</span><span class="p">[]);</span>
</pre></div>
</div>
<p>will provide a new list of indices in the local numbering. Again,
negative values in <code class="docutils notranslate"><span class="pre">idxin</span></code> are left unmapped. But in addition, if
<code class="docutils notranslate"><span class="pre">type</span></code> is set to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISGlobalToLocalMappingMode.html">IS_GTOLM_MASK</a></span></code> , then <code class="docutils notranslate"><span class="pre">nout</span></code> is set to <code class="docutils notranslate"><span class="pre">nin</span></code>
and all global values in <code class="docutils notranslate"><span class="pre">idxin</span></code> that are not represented in the local
to global mapping are replaced by -1. When <code class="docutils notranslate"><span class="pre">type</span></code> is set to
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISGlobalToLocalMappingMode.html">IS_GTOLM_DROP</a></span></code>, the values in <code class="docutils notranslate"><span class="pre">idxin</span></code> that are not represented
locally in the mapping are not included in <code class="docutils notranslate"><span class="pre">idxout</span></code>, so that
potentially <code class="docutils notranslate"><span class="pre">nout</span></code> is smaller than <code class="docutils notranslate"><span class="pre">nin</span></code>. One must pass in an array
long enough to hold all the indices. One can call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISGlobalToLocalMappingApplyBlock.html">ISGlobalToLocalMappingApplyBlock</a>()</span></code> with <code class="docutils notranslate"><span class="pre">idxout</span></code> equal to <code class="docutils notranslate"><span class="pre">NULL</span></code>
to determine the required length (returned in <code class="docutils notranslate"><span class="pre">nout</span></code>) and then
allocate the required space and call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/ISGlobalToLocalMappingApplyBlock.html">ISGlobalToLocalMappingApplyBlock</a>()</span></code> a second time to set the values.</p>
<p>Often it is convenient to set elements into a vector using the local
node numbering rather than the global node numbering (e.g., each process
may maintain its own sublist of vertices and elements and number them
locally). To set values into a vector with the local numbering, one must
first call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSetLocalToGlobalMapping.html">VecSetLocalToGlobalMapping</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">v</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">ctx</span><span class="p">);</span>
</pre></div>
</div>
<p>and then call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSetValuesLocal.html">VecSetValuesLocal</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="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="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">indices</span><span class="p">[],</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="n">values</span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">);</span>
</pre></div>
</div>
<p>Now the <code class="docutils notranslate"><span class="pre">indices</span></code> use the local numbering rather than the global,
meaning the entries lie in <span class="math">\([0,n)\)</span> where <span class="math">\(n\)</span> is the local
size of the vector. Global vectors obtained from a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> already have the global to local mapping
provided by the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>.</p>
<p>One can use global indices
with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValues.html">MatSetValues</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValuesStencil.html">MatSetValuesStencil</a>()</span></code> to assemble global stiffness matrices. Alternately, the
global node number of each local node, including the ghost nodes, can be
obtained by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DM/DMGetLocalToGlobalMapping.html">DMGetLocalToGlobalMapping</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="o">*</span><span class="n">map</span><span class="p">);</span>
</pre></div>
</div>
<p>followed by</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecSetLocalToGlobalMapping.html">VecSetLocalToGlobalMapping</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">v</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">map</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Mat/MatSetLocalToGlobalMapping.html">MatSetLocalToGlobalMapping</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">A</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">rmapping</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">cmapping</span><span class="p">);</span>
</pre></div>
</div>
<p>Now, entries may be added to the vector and matrix using the local
numbering and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecSetValuesLocal.html">VecSetValuesLocal</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatSetValuesLocal.html">MatSetValuesLocal</a>()</span></code>.</p>
<p>The example
<a href="../src/snes/tutorials/ex5.c.html">SNES Tutorial ex5</a>
illustrates the use of a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> in the solution of a
nonlinear problem. The analogous Fortran program is
<a href="../src/snes/tutorials/ex5f90.F90.html">SNES Tutorial ex5f90</a>;
see <a class="reference internal" href="snes.html#ch-snes"><span class="std std-ref">SNES: Nonlinear Solvers</span></a> for a discussion of the
nonlinear solvers.</p>
</section>
<section id="global-vectors-with-locations-for-ghost-values">
<span id="sec-vecghost"></span><h3>Global Vectors with locations for ghost values<a class="headerlink" href="#global-vectors-with-locations-for-ghost-values" title="Link to this heading">#</a></h3>
<p>There are two minor drawbacks to the basic approach described above for unstructured grids:</p>
<ul class="simple">
<li><p>the extra memory requirement for the local work vector, <code class="docutils notranslate"><span class="pre">localin</span></code>,
which duplicates the local values in the memory in <code class="docutils notranslate"><span class="pre">globalin</span></code>, and</p></li>
<li><p>the extra time required to copy the local values from <code class="docutils notranslate"><span class="pre">localin</span></code> to
<code class="docutils notranslate"><span class="pre">globalin</span></code>.</p></li>
</ul>
<p>An alternative approach is to allocate global vectors with space
preallocated for the ghost values.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreateGhost.html">VecCreateGhost</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nghost</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">ghosts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">vv</span><span class="p">)</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecCreateGhostWithArray.html">VecCreateGhostWithArray</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">N</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nghost</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">ghosts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="w"> </span><span class="o">*</span><span class="n">array</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">vv</span><span class="p">)</span>
</pre></div>
</div>
<p>Here <code class="docutils notranslate"><span class="pre">n</span></code> is the number of local vector entries, <code class="docutils notranslate"><span class="pre">N</span></code> is the number of
global entries (or <code class="docutils notranslate"><span class="pre">NULL</span></code>), and <code class="docutils notranslate"><span class="pre">nghost</span></code> is the number of ghost
entries. The array <code class="docutils notranslate"><span class="pre">ghosts</span></code> is of size <code class="docutils notranslate"><span class="pre">nghost</span></code> and contains the
global vector location for each local ghost location. Using
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicate.html">VecDuplicate</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecDuplicateVecs.html">VecDuplicateVecs</a>()</span></code> on a ghosted vector will
generate additional ghosted vectors.</p>
<p>In many ways, a ghosted vector behaves like any other MPI vector
created by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecCreateMPI.html">VecCreateMPI</a>()</span></code>. The difference is that the ghosted vector
has an additional “local” representation that allows one to access the
ghost locations. This is done through the call to</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGhostGetLocalForm.html">VecGhostGetLocalForm</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">g</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">l</span><span class="p">);</span>
</pre></div>
</div>
<p>The vector <code class="docutils notranslate"><span class="pre">l</span></code> is a sequential representation of the parallel vector
<code class="docutils notranslate"><span class="pre">g</span></code> that shares the same array space (and hence numerical values); but
allows one to access the “ghost” values past “the end of the” array.
Note that one accesses the entries in <code class="docutils notranslate"><span class="pre">l</span></code> using the local numbering of
elements and ghosts, while they are accessed in <code class="docutils notranslate"><span class="pre">g</span></code> using the global
numbering.</p>
<p>A common usage of a ghosted vector is given by</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Vec/VecGhostUpdateBegin.html">VecGhostUpdateBegin</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">globalin</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGhostUpdateEnd.html">VecGhostUpdateEnd</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">globalin</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGhostGetLocalForm.html">VecGhostGetLocalForm</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">globalin</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">localin</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGhostGetLocalForm.html">VecGhostGetLocalForm</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">globalout</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">localout</span><span class="p">);</span>
<span class="p">...</span><span class="w">  </span><span class="n">Do</span><span class="w"> </span><span class="n">local</span><span class="w"> </span><span class="n">calculations</span><span class="w"> </span><span class="n">from</span><span class="w"> </span><span class="n">localin</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">localout</span><span class="w"> </span><span class="p">...</span>
<span class="n"><a href="../manualpages/Vec/VecGhostRestoreLocalForm.html">VecGhostRestoreLocalForm</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">globalin</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">localin</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGhostRestoreLocalForm.html">VecGhostRestoreLocalForm</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">globalout</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">localout</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGhostUpdateBegin.html">VecGhostUpdateBegin</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">globalout</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/Vec/VecGhostUpdateEnd.html">VecGhostUpdateEnd</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">globalout</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/InsertMode.html">InsertMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/ScatterMode.html">ScatterMode</a></span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span><span class="p">);</span>
</pre></div>
</div>
<p>The routines <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGhostUpdateBegin.html">VecGhostUpdateBegin</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecGhostUpdateEnd.html">VecGhostUpdateEnd</a>()</span></code> are
equivalent to the routines <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterBegin.html">VecScatterBegin</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/VecScatterEnd.html">VecScatterEnd</a>()</span></code>
above, except that since they are scattering into the ghost locations,
they do not need to copy the local vector values, which are already in
place. In addition, the user does not have to allocate the local work
vector since the ghosted vector already has allocated slots to contain
the ghost values.</p>
<p>The input arguments <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/INSERT_VALUES.html">INSERT_VALUES</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/SCATTER_FORWARD.html">SCATTER_FORWARD</a></span></code> cause the
ghost values to be correctly updated from the appropriate process. The
arguments <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/ADD_VALUES.html">ADD_VALUES</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span></code> update the “local”
portions of the vector from all the other processes’ ghost values. This
would be appropriate, for example, when performing a finite element
assembly of a load vector. One can also use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/MAX_VALUES.html">MAX_VALUES</a></span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/MIN_VALUES.html">MIN_VALUES</a></span></code> with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/SCATTER_REVERSE.html">SCATTER_REVERSE</a></span></code>.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMPlex/DMPLEX.html">DMPLEX</a></span></code> does not yet support ghosted vectors sharing memory with the global representation.
This is a work in progress; if you are interested in this feature, please contact the PETSc community members.</p>
<p><a class="reference internal" href="mat.html#sec-partitioning"><span class="std std-ref">Partitioning</span></a> discusses the important topic of
partitioning an unstructured grid.</p>
</section>
</section>
<section id="application-orderings">
<span id="sec-ao"></span><h2>Application Orderings<a class="headerlink" href="#application-orderings" title="Link to this heading">#</a></h2>
<p>When writing parallel PDE codes, there is extra complexity caused by
having multiple ways of indexing (numbering) and ordering objects such
as vertices and degrees of freedom. For example, a grid generator or
partitioner may renumber the nodes, requiring adjustment of the other
data structures that refer to these objects; see Figure
<a class="reference internal" href="#fig-daao"><span class="std std-ref">Natural Ordering and PETSc Ordering for a 2D Distributed Array (Four
Processes)</span></a>.
PETSc provides various tools to help manage the mapping amongst
the various numbering systems. The most basic is the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code>
(application ordering), which enables mapping between different global
(cross-process) numbering schemes.</p>
<p>In many applications, it is desirable to work with one or more
“orderings” (or numberings) of degrees of freedom, cells, nodes, etc.
Doing so in a parallel environment is complicated by the fact that each
process cannot keep complete lists of the mappings between different
orderings. In addition, the orderings used in the PETSc linear algebra
routines (often contiguous ranges) may not correspond to the “natural”
orderings for the application.</p>
<p>PETSc provides certain utility routines that allow one to deal cleanly
and efficiently with the various orderings. To define a new application
ordering (called an <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> in PETSc), one can call the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/AO/AOCreateBasic.html">AOCreateBasic</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">apordering</span><span class="p">[],</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">petscordering</span><span class="p">[],</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="o">*</span><span class="n">ao</span><span class="p">);</span>
</pre></div>
</div>
<p>The arrays <code class="docutils notranslate"><span class="pre">apordering</span></code> and <code class="docutils notranslate"><span class="pre">petscordering</span></code>, respectively, contain a
list of integers in the application ordering and their corresponding
mapped values in the PETSc ordering. Each process can provide whatever
subset of the ordering it chooses, but multiple processes should never
contribute duplicate values. The argument <code class="docutils notranslate"><span class="pre">n</span></code> indicates the number of
local contributed values.</p>
<p>For example, consider a vector of length 5, where node 0 in the
application ordering corresponds to node 3 in the PETSc ordering. In
addition, nodes 1, 2, 3, and 4 of the application ordering correspond,
respectively, to nodes 2, 1, 4, and 0 of the PETSc ordering. We can
write this correspondence as</p>
<div class="math">
\[
\{ 0, 1, 2, 3, 4 \}  \to  \{ 3, 2, 1, 4, 0 \}.
\]</div>
<p>The user can create the PETSc <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> mappings in several ways. For
example, if using two processes, one could call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/AO/AOCreateBasic.html">AOCreateBasic</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="mi">2</span><span class="p">,{</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">},{</span><span class="mi">3</span><span class="p">,</span><span class="mi">4</span><span class="p">},</span><span class="o">&amp;</span><span class="n">ao</span><span class="p">);</span>
</pre></div>
</div>
<p>on the first process and</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/AO/AOCreateBasic.html">AOCreateBasic</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="mi">3</span><span class="p">,{</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">},{</span><span class="mi">2</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">0</span><span class="p">},</span><span class="o">&amp;</span><span class="n">ao</span><span class="p">);</span>
</pre></div>
</div>
<p>on the other process.</p>
<p>Once the application ordering has been created, it can be used with
either of the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/AO/AOPetscToApplication.html">AOPetscToApplication</a></span><span class="p">(</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="n">ao</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">indices</span><span class="p">);</span>
<span class="n"><a href="../manualpages/AO/AOApplicationToPetsc.html">AOApplicationToPetsc</a></span><span class="p">(</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="n">ao</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">n</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="o">*</span><span class="n">indices</span><span class="p">);</span>
</pre></div>
</div>
<p>Upon input, the <code class="docutils notranslate"><span class="pre">n</span></code>-dimensional array <code class="docutils notranslate"><span class="pre">indices</span></code> specifies the
indices to be mapped, while upon output, <code class="docutils notranslate"><span class="pre">indices</span></code> contains the mapped
values. Since we, in general, employ a parallel database for the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code>
mappings, it is crucial that all processes that called
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AOCreateBasic.html">AOCreateBasic</a>()</span></code> also call these routines; these routines <em>cannot</em> be
called by just a subset of processes in the MPI communicator that was
used in the call to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AOCreateBasic.html">AOCreateBasic</a>()</span></code>.</p>
<p>An alternative routine to create the application ordering, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code>, is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/AO/AOCreateBasicIS.html">AOCreateBasicIS</a></span><span class="p">(</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">apordering</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">petscordering</span><span class="p">,</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="o">*</span><span class="n">ao</span><span class="p">);</span>
</pre></div>
</div>
<p>where index sets are used
instead of integer arrays.</p>
<p>The mapping routines</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/AO/AOPetscToApplicationIS.html">AOPetscToApplicationIS</a></span><span class="p">(</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="n">ao</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">indices</span><span class="p">);</span>
<span class="n"><a href="../manualpages/AO/AOApplicationToPetscIS.html">AOApplicationToPetscIS</a></span><span class="p">(</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="n">ao</span><span class="p">,</span><span class="n"><a href="../manualpages/IS/IS.html">IS</a></span><span class="w"> </span><span class="n">indices</span><span class="p">);</span>
</pre></div>
</div>
<p>will map index sets (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/IS/IS.html">IS</a></span></code> objects) between orderings. Both the
<code class="docutils notranslate"><span class="pre">AOXxxToYyy()</span></code> and <code class="docutils notranslate"><span class="pre">AOXxxToYyyIS()</span></code> routines can be used regardless
of whether the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> was created with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AOCreateBasic.html">AOCreateBasic</a>()</span></code> or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AOCreateBasicIS.html">AOCreateBasicIS</a>()</span></code>.</p>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> context should be destroyed with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AODestroy.html">AODestroy</a>(<a href="../manualpages/AO/AO.html">AO</a></span> <span class="pre">*ao)</span></code> and
viewed with <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AOView.html">AOView</a>(<a href="../manualpages/AO/AO.html">AO</a></span> <span class="pre">ao,<a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span> <span class="pre">viewer)</span></code>.</p>
<p>Although we refer to the two orderings as “PETSc” and “application”
orderings, the user is free to use them both for application orderings
and to maintain relationships among a variety of orderings by employing
several <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> contexts.</p>
<p>The <code class="docutils notranslate"><span class="pre">AOxxToxx()</span></code> routines allow negative entries in the input integer
array. These entries are not mapped; they remain unchanged. This
functionality enables, for example, mapping neighbor lists that use
negative numbers to indicate nonexistent neighbors due to boundary
conditions, etc.</p>
<p>Since the global ordering that PETSc uses to manage its parallel vectors
(and matrices) does not usually correspond to the “natural” ordering of
a two- or three-dimensional array, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code> structure provides an
application ordering <code class="docutils notranslate"><span class="pre"><a href="../manualpages/AO/AO.html">AO</a></span></code> (see <a class="reference internal" href="#sec-ao"><span class="std std-ref">Application Orderings</span></a>) that maps
between the natural ordering on a rectangular grid and the ordering
PETSc uses to parallelize. This ordering context can be obtained with
the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/DMDA/DMDAGetAO.html">DMDAGetAO</a></span><span class="p">(</span><span class="n"><a href="../manualpages/DM/DM.html">DM</a></span><span class="w"> </span><span class="n">da</span><span class="p">,</span><span class="n"><a href="../manualpages/AO/AO.html">AO</a></span><span class="w"> </span><span class="o">*</span><span class="n">ao</span><span class="p">);</span>
</pre></div>
</div>
<p>In Figure <a class="reference internal" href="#fig-daao"><span class="std std-ref">Natural Ordering and PETSc Ordering for a 2D Distributed Array (Four
Processes)</span></a>, we indicate the orderings for a
two-dimensional <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DMDA/DMDA.html">DMDA</a></span></code>, divided among four processes.</p>
<figure class="align-default" id="fig-daao">
<img alt="Natural Ordering and PETSc Ordering for a 2D Distributed Array (Four Processes)" src="../_images/danumbering.png" />
<figcaption>
<p><span class="caption-number">Fig. 4 </span><span class="caption-text">Natural Ordering and PETSc Ordering for a 2D Distributed Array (Four
Processes)</span><a class="headerlink" href="#fig-daao" title="Link to this image">#</a></p>
</figcaption>
</figure>
</section>
</section>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="programming.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 Solvers in PETSc/TAO</p>
      </div>
    </a>
    <a class="right-next"
       href="mat.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">Matrices</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            
              
                <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#creating-vectors">Creating Vectors</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmda-creating-vectors-for-structured-grids">DMDA - Creating vectors for structured grids</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmstag-creating-vectors-for-staggered-grids">DMSTAG - Creating vectors for staggered grids</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmplex-creating-vectors-for-unstructured-grids">DMPLEX - Creating vectors for unstructured grids</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmnetwork-creating-vectors-for-networks">DMNETWORK - Creating vectors for networks</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#common-vector-functions-and-operations">Common vector functions and operations</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#assembling-putting-values-in-vectors">Assembling (putting values in) vectors</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmda-setting-vector-values">DMDA - Setting vector values</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmstag-setting-vector-values">DMSTAG - Setting vector values</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmplex-setting-vector-values">DMPLEX - Setting vector values</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#dmnetwork-setting-vector-values">DMNETWORK - Setting vector values</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#basic-vector-operations">Basic Vector Operations</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#local-global-vectors-and-communicating-between-vectors">Local/global vectors and communicating between vectors</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#low-level-vector-communication">Low-level Vector Communication</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#local-to-global-mappings">Local to global mappings</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#global-vectors-with-locations-for-ghost-values">Global Vectors with locations for ghost values</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#application-orderings">Application Orderings</a></li>
</ul>
  </nav></div>

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

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