File: ts.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 (2400 lines) | stat: -rw-r--r-- 187,731 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>TS: Scalable ODE and DAE Solvers &#8212; PETSc 3.23.1 documentation</title>
  
  
  
  <script data-cfasync="false">
    document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
    document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
  </script>
  
  <!-- Loaded before other Sphinx assets -->
  <link href="../_static/styles/theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />

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

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

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

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

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

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

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

  

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    </div>
  
  </header>

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

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

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

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

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

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

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

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

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

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

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

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

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






</ul>
</li>
<li class="toctree-l2 current active has-children"><a class="reference internal" href="programming.html">The Solvers in PETSc/TAO</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-3"><i class="fa-solid fa-chevron-down"></i></label><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="vec.html">Vectors and Parallel Data</a></li>
<li class="toctree-l3"><a class="reference internal" href="mat.html">Matrices</a></li>
<li class="toctree-l3"><a class="reference internal" href="ksp.html">KSP: Linear System Solvers</a></li>
<li class="toctree-l3"><a class="reference internal" href="snes.html">SNES: Nonlinear Solvers</a></li>
<li class="toctree-l3 current active"><a class="current reference internal" href="#">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">TS:...</li>
  </ul>
</nav>
</div>
      
    </div>
  
  
</div>
</div>
              
              
              
                
<div id="searchbox"></div>
                <article class="bd-article">
                  
  <section class="tex2jax_ignore mathjax_ignore" id="ts-scalable-ode-and-dae-solvers">
<span id="ch-ts"></span><h1>TS: Scalable ODE and DAE Solvers<a class="headerlink" href="#ts-scalable-ode-and-dae-solvers" title="Link to this heading">#</a></h1>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> library provides a framework for the scalable solution of
ODEs and DAEs arising from the discretization of time-dependent PDEs.</p>
<p><strong>Simple Example:</strong> Consider the PDE</p>
<div class="math">
\[
u_t = u_{xx}
\]</div>
<p>discretized with centered finite differences in space yielding the
semi-discrete equation</p>
<div class="math">
\[
\begin{aligned}
          (u_i)_t & =  & \frac{u_{i+1} - 2 u_{i} + u_{i-1}}{h^2}, \\
           u_t      &  = & \tilde{A} u;\end{aligned}
\]</div>
<p>or with piecewise linear finite elements approximation in space
<span class="math">\(u(x,t) \doteq \sum_i \xi_i(t) \phi_i(x)\)</span> yielding the
semi-discrete equation</p>
<div class="math">
\[
B {\xi}'(t) = A \xi(t)
\]</div>
<p>Now applying the backward Euler method results in</p>
<div class="math">
\[
( B - dt^n A  ) u^{n+1} = B u^n,
\]</div>
<p>in which</p>
<div class="math">
\[
{u^n}_i = \xi_i(t_n) \doteq u(x_i,t_n),
\]</div>
<div class="math">
\[
{\xi}'(t_{n+1}) \doteq \frac{{u^{n+1}}_i - {u^{n}}_i }{dt^{n}},
\]</div>
<p><span class="math">\(A\)</span> is the stiffness matrix, and <span class="math">\(B\)</span> is the identity for
finite differences or the mass matrix for the finite element method.</p>
<p>The PETSc interface for solving time dependent problems assumes the
problem is written in the form</p>
<div class="math">
\[
F(t,u,\dot{u}) = G(t,u), \quad u(t_0) = u_0.
\]</div>
<p>In general, this is a differential algebraic equation (DAE) <a class="footnote-reference brackets" href="#id9" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. For
ODE with nontrivial mass matrices such as arise in FEM, the implicit/DAE
interface significantly reduces overhead to prepare the system for
algebraic solvers (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>/<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>) by having the user assemble the
correctly shifted matrix. Therefore this interface is also useful for
ODE systems.</p>
<p>To solve an ODE or DAE one uses:</p>
<ul>
<li><p>Function <span class="math">\(F(t,u,\dot{u})\)</span></p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">R</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">f</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">funP</span><span class="p">);</span>
</pre></div>
</div>
<p>The vector <code class="docutils notranslate"><span class="pre">R</span></code> is an optional location to store the residual. The
arguments to the function <code class="docutils notranslate"><span class="pre">f()</span></code> are the timestep context, current
time, input state <span class="math">\(u\)</span>, input time derivative <span class="math">\(\dot{u}\)</span>,
and the (optional) user-provided context <code class="docutils notranslate"><span class="pre">funP</span></code>. If
<span class="math">\(F(t,u,\dot{u}) = \dot{u}\)</span> then one need not call this
function.</p>
</li>
<li><p>Function <span class="math">\(G(t,u)\)</span>, if it is nonzero, is provided with the
function</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">R</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">f</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">funP</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p>Jacobian</p>
<p><span class="math">\(\sigma F_{\dot{u}}(t^n,u^n,\dot{u}^n) + F_u(t^n,u^n,\dot{u}^n)\)</span></p>
<p>If using a fully implicit or semi-implicit (IMEX) method one also
can provide an appropriate (approximate) Jacobian matrix of</p>
<p><span class="math">\(F()\)</span></p>
<p>.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetIJacobian.html">TSSetIJacobian</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">B</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">fjac</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">jacP</span><span class="p">);</span>
</pre></div>
</div>
<p>The arguments for the function <code class="docutils notranslate"><span class="pre">fjac()</span></code> are the timestep context,
current time, input state <span class="math">\(u\)</span>, input derivative
<span class="math">\(\dot{u}\)</span>, input shift <span class="math">\(\sigma\)</span>, matrix <span class="math">\(A\)</span>,
preconditioning matrix <span class="math">\(B\)</span>, and the (optional) user-provided
context <code class="docutils notranslate"><span class="pre">jacP</span></code>.</p>
<p>The Jacobian needed for the nonlinear system is, by the chain rule,</p>
<div class="math">
\[
  \begin{aligned}
      \frac{d F}{d u^n} &  = &  \frac{\partial F}{\partial \dot{u}}|_{u^n} \frac{\partial \dot{u}}{\partial u}|_{u^n} + \frac{\partial F}{\partial u}|_{u^n}.\end{aligned}
  \]</div>
<p>For any ODE integration method the approximation of <span class="math">\(\dot{u}\)</span>
is linear in <span class="math">\(u^n\)</span> hence
<span class="math">\(\frac{\partial \dot{u}}{\partial u}|_{u^n} = \sigma\)</span>, where
the shift <span class="math">\(\sigma\)</span> depends on the ODE integrator and time step
but not on the function being integrated. Thus</p>
<div class="math">
\[
  \begin{aligned}
      \frac{d F}{d u^n} &  = &    \sigma F_{\dot{u}}(t^n,u^n,\dot{u}^n) + F_u(t^n,u^n,\dot{u}^n).\end{aligned}
  \]</div>
<p>This explains why the user provide Jacobian is in the given form for
all integration methods. An equivalent way to derive the formula is
to note that</p>
<div class="math">
\[
  F(t^n,u^n,\dot{u}^n) = F(t^n,u^n,w+\sigma*u^n)
  \]</div>
<p>where <span class="math">\(w\)</span> is some linear combination of previous time solutions
of <span class="math">\(u\)</span> so that</p>
<div class="math">
\[
  \frac{d F}{d u^n} = \sigma F_{\dot{u}}(t^n,u^n,\dot{u}^n) + F_u(t^n,u^n,\dot{u}^n)
  \]</div>
<p>again by the chain rule.</p>
<p>For example, consider backward Euler’s method applied to the ODE
<span class="math">\(F(t, u, \dot{u}) = \dot{u} - f(t, u)\)</span> with
<span class="math">\(\dot{u} = (u^n - u^{n-1})/\delta t\)</span> and
<span class="math">\(\frac{\partial \dot{u}}{\partial u}|_{u^n} = 1/\delta t\)</span>
resulting in</p>
<div class="math">
\[
  \begin{aligned}
      \frac{d F}{d u^n} & = &   (1/\delta t)F_{\dot{u}} + F_u(t^n,u^n,\dot{u}^n).\end{aligned}
  \]</div>
<p>But <span class="math">\(F_{\dot{u}} = 1\)</span>, in this special case, resulting in the
expected Jacobian <span class="math">\(I/\delta t - f_u(t,u^n)\)</span>.</p>
</li>
<li><p>Jacobian</p>
<p><span class="math">\(G_u\)</span></p>
<p>If using a fully implicit method and the function</p>
<p><span class="math">\(G()\)</span></p>
<p>is
provided, one also can provide an appropriate (approximate)
Jacobian matrix of</p>
<p><span class="math">\(G()\)</span></p>
<p>.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">A</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">B</span><span class="p">,</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">fjac</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">jacP</span><span class="p">);</span>
</pre></div>
</div>
<p>The arguments for the function <code class="docutils notranslate"><span class="pre">fjac()</span></code> are the timestep context,
current time, input state <span class="math">\(u\)</span>, matrix <span class="math">\(A\)</span>,
preconditioning matrix <span class="math">\(B\)</span>, and the (optional) user-provided
context <code class="docutils notranslate"><span class="pre">jacP</span></code>.</p>
</li>
</ul>
<p>Providing appropriate <span class="math">\(F()\)</span> and <span class="math">\(G()\)</span> for your problem
allows for the easy runtime switching between explicit, semi-implicit
(IMEX), and fully implicit methods.</p>
<section id="basic-ts-options">
<span id="sec-ts-basic"></span><h2>Basic TS Options<a class="headerlink" href="#basic-ts-options" title="Link to this heading">#</a></h2>
<p>The user first creates a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> object with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf"><a href="../manualpages/TS/TSCreate.html">TSCreate</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/TS/TS.html">TS</a></span><span class="w"> </span><span class="o">*</span><span class="n">ts</span><span class="p">);</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf"><a href="../manualpages/TS/TSSetProblemType.html">TSSetProblemType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSProblemType.html">TSProblemType</a></span><span class="w"> </span><span class="n">problemtype</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSProblemType.html">TSProblemType</a></span></code> is one of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSProblemType.html">TS_LINEAR</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSProblemType.html">TS_NONLINEAR</a></span></code>.</p>
<p>To set up <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> for solving an ODE, one must set the “initial
conditions” for the ODE with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetSolution.html">TSSetSolution</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</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">initialsolution</span><span class="p">);</span>
</pre></div>
</div>
<p>One can set the solution method with the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetType.html">TSSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSType.html">TSType</a></span><span class="w"> </span><span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>Some of the currently supported types are <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSEULER.html">TSEULER</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK.html">TSRK</a></span></code> (Runge-Kutta), <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSBEULER.html">TSBEULER</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSCN.html">TSCN</a></span></code> (Crank-Nicolson), <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSTHETA.html">TSTHETA</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLLE.html">TSGLLE</a></span></code> (generalized linear), and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSPSEUDO.html">TSPSEUDO</a></span></code>.
They can also be set with the options database option <code class="docutils notranslate"><span class="pre">-ts_type</span> <span class="pre">euler,</span> <span class="pre">rk,</span> <span class="pre">beuler,</span> <span class="pre">cn,</span> <span class="pre">theta,</span> <span class="pre">gl,</span> <span class="pre">pseudo,</span> <span class="pre">sundials,</span> <span class="pre">eimex,</span> <span class="pre">arkimex,</span> <span class="pre">rosw</span></code>.
A list of available methods is given in <a class="reference internal" href="../overview/integrator_table.html#integrator-table"><span class="std std-ref">Summary of Time Integrators Available In PETSc</span></a>.</p>
<p>Set the initial time with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetTime.html">TSSetTime</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">time</span><span class="p">);</span>
</pre></div>
</div>
<p>One can change the timestep with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetTimeStep.html">TSSetTimeStep</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">dt</span><span class="p">);</span>
</pre></div>
</div>
<p>can determine the current timestep with the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSGetTimeStep.html">TSGetTimeStep</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="o">*</span><span class="w"> </span><span class="n">dt</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, “current” refers to the timestep being used to attempt to promote
the solution form <span class="math">\(u^n\)</span> to <span class="math">\(u^{n+1}.\)</span></p>
<p>One sets the total number of timesteps to run or the total time to run
(whatever is first) with the commands</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetMaxSteps.html">TSSetMaxSteps</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">maxsteps</span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetMaxTime.html">TSSetMaxTime</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">maxtime</span><span class="p">);</span>
</pre></div>
</div>
<p>and determines the behavior near the final time with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetExactFinalTime.html">TSSetExactFinalTime</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSExactFinalTimeOption.html">TSExactFinalTimeOption</a></span><span class="w"> </span><span class="n">eftopt</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">eftopt</span></code> is one of
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSExactFinalTimeOption.html">TS_EXACTFINALTIME_STEPOVER</a></span></code>,<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSExactFinalTimeOption.html">TS_EXACTFINALTIME_INTERPOLATE</a></span></code>, or
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSExactFinalTimeOption.html">TS_EXACTFINALTIME_MATCHSTEP</a></span></code>. One performs the requested number of
time steps with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSolve.html">TSSolve</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">U</span><span class="p">);</span>
</pre></div>
</div>
<p>The solve call implicitly sets up the timestep context; this can be done
explicitly with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetUp.html">TSSetUp</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">);</span>
</pre></div>
</div>
<p>One destroys the context with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSDestroy.html">TSDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="o">*</span><span class="n">ts</span><span class="p">);</span>
</pre></div>
</div>
<p>and views it with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSView.html">TSView</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span><span class="w"> </span><span class="n">viewer</span><span class="p">);</span>
</pre></div>
</div>
<p>In place of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSolve.html">TSSolve</a>()</span></code>, a single step can be taken using</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSStep.html">TSStep</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="dae-formulations">
<span id="sec-imex"></span><h2>DAE Formulations<a class="headerlink" href="#dae-formulations" title="Link to this heading">#</a></h2>
<p>You can find a discussion of DAEs in <span id="id2">[<a class="reference internal" href="#id1010" title="Uri M Ascher and Linda R Petzold. Computer methods for ordinary differential equations and differential-algebraic equations. Volume 61. SIAM, 1998.">AP98</a>]</span> or <a class="reference external" href="http://www.scholarpedia.org/article/Differential-algebraic_equations">Scholarpedia</a>. In PETSc, TS deals with the semi-discrete form of the equations, so that space has already been discretized. If the DAE depends explicitly on the coordinate <span class="math">\(x\)</span>, then this will just appear as any other data for the equation, not as an explicit argument. Thus we have</p>
<div class="math">
\[
F(t, u, \dot{u}) = 0
\]</div>
<p>In this form, only fully implicit solvers are appropriate. However, specialized solvers for restricted forms of DAE are supported by PETSc. Below we consider an ODE which is augmented with algebraic constraints on the variables.</p>
<section id="hessenberg-index-1-dae">
<h3>Hessenberg Index-1 DAE<a class="headerlink" href="#hessenberg-index-1-dae" title="Link to this heading">#</a></h3>
<blockquote>
<div><p>This is a Semi-Explicit Index-1 DAE which has the form</p>
</div></blockquote>
<div class="math">
\[
\begin{aligned}
  \dot{u} &= f(t, u, z) \\
        0 &= h(t, u, z)
\end{aligned}
\]</div>
<p>where <span class="math">\(z\)</span> is a new constraint variable, and the Jacobian <span class="math">\(\frac{dh}{dz}\)</span> is non-singular everywhere. We have suppressed the <span class="math">\(x\)</span> dependence since it plays no role here. Using the non-singularity of the Jacobian and the Implicit Function Theorem, we can solve for <span class="math">\(z\)</span> in terms of <span class="math">\(u\)</span>. This means we could, in principle, plug <span class="math">\(z(u)\)</span> into the first equation to obtain a simple ODE, even if this is not the numerical process we use. Below we show that this type of DAE can be used with IMEX schemes.</p>
</section>
<section id="hessenberg-index-2-dae">
<h3>Hessenberg Index-2 DAE<a class="headerlink" href="#hessenberg-index-2-dae" title="Link to this heading">#</a></h3>
<blockquote>
<div><p>This DAE has the form</p>
</div></blockquote>
<div class="math">
\[
\begin{aligned}
  \dot{u} &= f(t, u, z) \\
        0 &= h(t, u)
\end{aligned}
\]</div>
<p>Notice that the constraint equation <span class="math">\(h\)</span> is not a function of the constraint variable <span class="math">\(z\)</span>. This means that we cannot naively invert as we did in the index-1 case. Our strategy will be to convert this into an index-1 DAE using a time derivative, which loosely corresponds to the idea of an index being the number of derivatives necessary to get back to an ODE. If we differentiate the constraint equation with respect to time, we can use the ODE to simplify it,</p>
<div class="math">
\[
\begin{aligned}
        0 &= \dot{h}(t, u) \\
          &= \frac{dh}{du} \dot{u} + \frac{\partial h}{\partial t} \\
          &= \frac{dh}{du} f(t, u, z) + \frac{\partial h}{\partial t}
\end{aligned}
\]</div>
<p>If the Jacobian <span class="math">\(\frac{dh}{du} \frac{df}{dz}\)</span> is non-singular, then we have precisely a semi-explicit index-1 DAE, and we can once again use the PETSc IMEX tools to solve it. A common example of an index-2 DAE is the incompressible Navier-Stokes equations, since the continuity equation <span class="math">\(\nabla\cdot u = 0\)</span> does not involve the pressure. Using PETSc IMEX with the above conversion then corresponds to the Segregated Runge-Kutta method applied to this equation <span id="id3">[<a class="reference internal" href="#id1011" title="Oriol Colomés and Santiago Badia. Segregated Runge–Kutta methods for the incompressible Navier–Stokes equations. International Journal for Numerical Methods in Engineering, 105(5):372–400, 2016.">ColomesB16</a>]</span>.</p>
</section>
</section>
<section id="using-implicit-explicit-imex-methods">
<h2>Using Implicit-Explicit (IMEX) Methods<a class="headerlink" href="#using-implicit-explicit-imex-methods" title="Link to this heading">#</a></h2>
<p>For “stiff” problems or those with multiple time scales <span class="math">\(F()\)</span> will
be treated implicitly using a method suitable for stiff problems and
<span class="math">\(G()\)</span> will be treated explicitly when using an IMEX method like
TSARKIMEX. <span class="math">\(F()\)</span> is typically linear or weakly nonlinear while
<span class="math">\(G()\)</span> may have very strong nonlinearities such as arise in
non-oscillatory methods for hyperbolic PDE. The user provides three
pieces of information, the APIs for which have been described above.</p>
<ul class="simple">
<li><p>“Slow” part <span class="math">\(G(t,u)\)</span> using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a>()</span></code>.</p></li>
<li><p>“Stiff” part <span class="math">\(F(t,u,\dot u)\)</span> using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a>()</span></code>.</p></li>
<li><p>Jacobian <span class="math">\(F_u + \sigma F_{\dot u}\)</span> using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIJacobian.html">TSSetIJacobian</a>()</span></code>.</p></li>
</ul>
<p>The user needs to set <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetEquationType.html">TSSetEquationType</a>()</span></code> to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSEquationType.html">TS_EQ_IMPLICIT</a></span></code> or
higher if the problem is implicit; e.g.,
<span class="math">\(F(t,u,\dot u) = M \dot u - f(t,u)\)</span>, where <span class="math">\(M\)</span> is not the
identity matrix:</p>
<ul class="simple">
<li><p>the problem is an implicit ODE (defined implicitly through
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a>()</span></code>) or</p></li>
<li><p>a DAE is being solved.</p></li>
</ul>
<p>An IMEX problem representation can be made implicit by setting <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSARKIMEXSetFullyImplicit.html">TSARKIMEXSetFullyImplicit</a>()</span></code>.
Note that multilevel preconditioners (e.g. <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCMG.html">PCMG</a></span></code>), won’t work in the fully implicit case; the
same holds true for any other <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> type requiring a fully implicit formulation in case both
Jacobians are specified.</p>
<p>In PETSc, DAEs and ODEs are formulated as <span class="math">\(F(t,u,\dot{u})=G(t,u)\)</span>, where <span class="math">\(F()\)</span> is meant to be integrated implicitly and <span class="math">\(G()\)</span> explicitly. An IMEX formulation such as <span class="math">\(M\dot{u}=f(t,u)+g(t,u)\)</span> requires the user to provide <span class="math">\(M^{-1} g(t,u)\)</span> or solve <span class="math">\(g(t,u) - M x=0\)</span> in place of <span class="math">\(G(t,u)\)</span>. General cases such as <span class="math">\(F(t,u,\dot{u})=G(t,u)\)</span> are not amenable to IMEX Runge-Kutta, but can be solved by using fully implicit methods. Some use-case examples for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSARKIMEX.html">TSARKIMEX</a></span></code> are listed in <a class="reference internal" href="#tab-de-forms"><span class="std std-numref">Table 13</span></a> and a list of methods with a summary of their properties is given in <a class="reference internal" href="#tab-imex-rk-petsc"><span class="std std-ref">IMEX Runge-Kutta schemes</span></a>.</p>
<table class="table" id="tab-de-forms">
<caption><span class="caption-number">Table 13 </span><span class="caption-text">Use case examples for <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSARKIMEX.html">TSARKIMEX</a></span></code></span><a class="headerlink" href="#tab-de-forms" title="Link to this table">#</a></caption>
<colgroup>
<col style="width: 25.0%" />
<col style="width: 25.0%" />
<col style="width: 50.0%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><span class="math">\(\dot{u} = g(t,u)\)</span></p></td>
<td><p>nonstiff ODE</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= \dot{u} \\ G(t,u) &amp;= g(t,u)\end{aligned}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><span class="math">\(M \dot{u} = g(t,u)\)</span></p></td>
<td><p>nonstiff ODE with mass matrix</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= \dot{u} \\ G(t,u) &amp;= M^{-1} g(t,u)\end{aligned}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><span class="math">\(\dot{u} = f(t,u)\)</span></p></td>
<td><p>stiff ODE</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= \dot{u} - f(t,u) \\ G(t,u) &amp;= 0\end{aligned}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><span class="math">\(M \dot{u} = f(t,u)\)</span></p></td>
<td><p>stiff ODE with mass matrix</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= M \dot{u} - f(t,u) \\ G(t,u) &amp;= 0\end{aligned}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><span class="math">\(\dot{u} = f(t,u) + g(t,u)\)</span></p></td>
<td><p>stiff-nonstiff ODE</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= \dot{u} - f(t,u) \\ G(t,u) &amp;= g(t,u)\end{aligned}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><span class="math">\(M \dot{u} = f(t,u) + g(t,u)\)</span></p></td>
<td><p>stiff-nonstiff ODE with mass matrix</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= M\dot{u} - f(t,u) \\ G(t,u) &amp;= M^{-1} g(t,u)\end{aligned}\)</span></p></td>
</tr>
<tr class="row-odd"><td><p><span class="math">\(\begin{aligned}\dot{u} &amp;= f(t,u,z) + g(t,u,z)\\0 &amp;= h(t,y,z)\end{aligned}\)</span></p></td>
<td><p>semi-explicit index-1 DAE</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= \begin{pmatrix}\dot{u} - f(t,u,z)\\h(t, u, z)\end{pmatrix}\\G(t,u) &amp;= g(t,u)\end{aligned}\)</span></p></td>
</tr>
<tr class="row-even"><td><p><span class="math">\(f(t,u,\dot{u})=0\)</span></p></td>
<td><p>fully implicit ODE/DAE</p></td>
<td><p><span class="math">\(\begin{aligned}F(t,u,\dot{u}) &amp;= f(t,u,\dot{u})\\G(t,u) &amp;= 0\end{aligned}\)</span>; the user needs to set <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetEquationType.html">TSSetEquationType</a>()</span></code> to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSEquationType.html">TS_EQ_IMPLICIT</a></span></code> or higher</p></td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="#tab-imex-rk-petsc"><span class="std std-numref">Table 14</span></a> lists of the currently available IMEX Runge-Kutta schemes. For each method, it gives the <code class="docutils notranslate"><span class="pre">-ts_arkimex_type</span></code> name, the reference, the total number of stages/implicit stages, the order/stage-order, the implicit stability properties (IM), stiff accuracy (SA), the existence of an embedded scheme, and dense output (DO).</p>
<table class="table" id="tab-imex-rk-petsc">
<caption><span class="caption-number">Table 14 </span><span class="caption-text">IMEX Runge-Kutta schemes</span><a class="headerlink" href="#tab-imex-rk-petsc" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Name</p></th>
<th class="head"><p>Reference</p></th>
<th class="head"><p>Stages (IM)</p></th>
<th class="head"><p>Order (Stage)</p></th>
<th class="head"><p>IM</p></th>
<th class="head"><p>SA</p></th>
<th class="head"><p>Embed</p></th>
<th class="head"><p>DO</p></th>
<th class="head"><p>Remarks</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>a2</p></td>
<td><p>based on CN</p></td>
<td><p>2 (1)</p></td>
<td><p>2 (2)</p></td>
<td><p>A-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (1)</p></td>
<td><p>yes (2)</p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p>l2</p></td>
<td><p>SSP2(2,2,2) <span id="id1">[<a class="reference internal" href="../manualpages/TS/TSARKIMEXPRSSP2.html#id1007" title="L. Pareschi and G. Russo. Implicit-explicit Runge-Kutta schemes and applications to hyperbolic systems with relaxation. Journal of Scientific Computing, 25(1):129–155, 2005.">PR05</a>]</span></p></td>
<td><p>2 (2)</p></td>
<td><p>2 (1)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (1)</p></td>
<td><p>yes (2)</p></td>
<td><p>SSP SDIRK</p></td>
</tr>
<tr class="row-even"><td><p>ars122</p></td>
<td><p>ARS122 <span id="id2">[<a class="reference internal" href="../manualpages/TS/TSARKIMEXARS443.html#id1010" title="U.M. Ascher, S.J. Ruuth, and R.J. Spiteri. Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151–167, 1997.">ARS97</a>]</span></p></td>
<td><p>2 (1)</p></td>
<td><p>3 (1)</p></td>
<td><p>A-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (1)</p></td>
<td><p>yes (2)</p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p>2c</p></td>
<td><p><span id="id3">[<a class="reference internal" href="#id1004" title="F.X. Giraldo, J.F. Kelly, and E.M. Constantinescu. Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA). SIAM Journal on Scientific Computing, 35(5):B1162-B1194, 2013. doi:10.1137/120876034.">GKC13</a>]</span></p></td>
<td><p>3 (2)</p></td>
<td><p>2 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (1)</p></td>
<td><p>yes (2)</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-even"><td><p>2d</p></td>
<td><p><span id="id4">[<a class="reference internal" href="#id1004" title="F.X. Giraldo, J.F. Kelly, and E.M. Constantinescu. Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA). SIAM Journal on Scientific Computing, 35(5):B1162-B1194, 2013. doi:10.1137/120876034.">GKC13</a>]</span></p></td>
<td><p>3 (2)</p></td>
<td><p>2 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (1)</p></td>
<td><p>yes (2)</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-odd"><td><p>2e</p></td>
<td><p><span id="id5">[<a class="reference internal" href="#id1004" title="F.X. Giraldo, J.F. Kelly, and E.M. Constantinescu. Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA). SIAM Journal on Scientific Computing, 35(5):B1162-B1194, 2013. doi:10.1137/120876034.">GKC13</a>]</span></p></td>
<td><p>3 (2)</p></td>
<td><p>2 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (1)</p></td>
<td><p>yes (2)</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-even"><td><p>prssp2</p></td>
<td><p>PRS(3,3,2) <span id="id6">[<a class="reference internal" href="../manualpages/TS/TSARKIMEXPRSSP2.html#id1007" title="L. Pareschi and G. Russo. Implicit-explicit Runge-Kutta schemes and applications to hyperbolic systems with relaxation. Journal of Scientific Computing, 25(1):129–155, 2005.">PR05</a>]</span></p></td>
<td><p>3 (3)</p></td>
<td><p>3 (1)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>no</p></td>
<td><p>no</p></td>
<td><p>SSP</p></td>
</tr>
<tr class="row-odd"><td><p>3</p></td>
<td><p><span id="id7">[<a class="reference internal" href="../manualpages/TS/TSARKIMEX5.html#id1008" title="C.A. Kennedy and M.H. Carpenter. Additive Runge-Kutta schemes for convection-diffusion-reaction equations. Appl. Numer. Math., 44(1-2):139–181, 2003. doi:10.1016/S0168-9274(02)00138-1.">KC03</a>]</span></p></td>
<td><p>4 (3)</p></td>
<td><p>3 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (2)</p></td>
<td><p>yes (2)</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-even"><td><p>bpr3</p></td>
<td><p><span id="id8">[<a class="reference internal" href="#id1008" title="S. Boscarino, L. Pareschi, and G. Russo. Implicit-explicit Runge-Kutta schemes for hyperbolic systems and kinetic equations in the diffusion limit. Arxiv preprint arXiv:1110.4375, 2011.">BPR11</a>]</span></p></td>
<td><p>5 (4)</p></td>
<td><p>3 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>no</p></td>
<td><p>no</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-odd"><td><p>ars443</p></td>
<td><p><span id="id9">[<a class="reference internal" href="../manualpages/TS/TSARKIMEXARS443.html#id1010" title="U.M. Ascher, S.J. Ruuth, and R.J. Spiteri. Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. Applied Numerical Mathematics, 25:151–167, 1997.">ARS97</a>]</span></p></td>
<td><p>5 (4)</p></td>
<td><p>3 (1)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>no</p></td>
<td><p>no</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-even"><td><p>4</p></td>
<td><p><span id="id10">[<a class="reference internal" href="../manualpages/TS/TSARKIMEX5.html#id1008" title="C.A. Kennedy and M.H. Carpenter. Additive Runge-Kutta schemes for convection-diffusion-reaction equations. Appl. Numer. Math., 44(1-2):139–181, 2003. doi:10.1016/S0168-9274(02)00138-1.">KC03</a>]</span></p></td>
<td><p>6 (5)</p></td>
<td><p>4 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (3)</p></td>
<td><p>yes</p></td>
<td><p>SDIRK</p></td>
</tr>
<tr class="row-odd"><td><p>5</p></td>
<td><p><span id="id11">[<a class="reference internal" href="../manualpages/TS/TSARKIMEX5.html#id1008" title="C.A. Kennedy and M.H. Carpenter. Additive Runge-Kutta schemes for convection-diffusion-reaction equations. Appl. Numer. Math., 44(1-2):139–181, 2003. doi:10.1016/S0168-9274(02)00138-1.">KC03</a>]</span></p></td>
<td><p>8 (7)</p></td>
<td><p>5 (2)</p></td>
<td><p>L-Stable</p></td>
<td><p>yes</p></td>
<td><p>yes (4)</p></td>
<td><p>yes (3)</p></td>
<td><p>SDIRK</p></td>
</tr>
</tbody>
</table>
<p>ROSW are linearized implicit Runge-Kutta methods known as Rosenbrock
W-methods. They can accommodate inexact Jacobian matrices in their
formulation. A series of methods are available in PETSc are listed in
<a class="reference internal" href="#tab-imex-rosw-petsc"><span class="std std-numref">Table 15</span></a> below. For each method, it gives the reference, the total number of stages and implicit stages, the scheme order and stage order, the implicit stability properties (IM), stiff accuracy (SA), the existence of an embedded scheme, dense output (DO), the capacity to use inexact Jacobian matrices (-W), and high order integration of differential algebraic equations (PDAE).</p>
<table class="table" id="tab-imex-rosw-petsc">
<caption><span class="caption-number">Table 15 </span><span class="caption-text">Rosenbrock W-schemes</span><a class="headerlink" href="#tab-imex-rosw-petsc" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>TS</p></th>
<th class="head"><p>Reference</p></th>
<th class="head"><p>Stages (IM)</p></th>
<th class="head"><p>Order (Stage)</p></th>
<th class="head"><p>IM</p></th>
<th class="head"><p>SA</p></th>
<th class="head"><p>Embed</p></th>
<th class="head"><p>DO</p></th>
<th class="head"><p>-W</p></th>
<th class="head"><p>PDAE</p></th>
<th class="head"><p>Remarks</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>theta1</p></td>
<td><p>classical</p></td>
<td><p>1(1)</p></td>
<td><p>1(1)</p></td>
<td><p>L-Stable</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>theta2</p></td>
<td><p>classical</p></td>
<td><p>1(1)</p></td>
<td><p>2(2)</p></td>
<td><p>A-Stable</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p>2m</p></td>
<td><p>Zoltan</p></td>
<td><p>2(2)</p></td>
<td><p>2(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes(1)</p></td>
<td><p>Yes(2)</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>SSP</p></td>
</tr>
<tr class="row-odd"><td><p>2p</p></td>
<td><p>Zoltan</p></td>
<td><p>2(2)</p></td>
<td><p>2(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes(1)</p></td>
<td><p>Yes(2)</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>SSP</p></td>
</tr>
<tr class="row-even"><td><p>ra3pw</p></td>
<td><p><span id="id1">[<a class="reference internal" href="../manualpages/TS/TSROSWRA3PW.html#id1014" title="J. Rang and L. Angermann. New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1. BIT Numerical Mathematics, 45(4):761–787, 2005. doi:10.1007/s10543-005-0035-y.">RA05</a>]</span></p></td>
<td><p>3(3)</p></td>
<td><p>3(1)</p></td>
<td><p>A-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes</p></td>
<td><p>Yes(2)</p></td>
<td><p>No</p></td>
<td><p>Yes(3)</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>ra34pw2</p></td>
<td><p><span id="id2">[<a class="reference internal" href="../manualpages/TS/TSROSWRA3PW.html#id1014" title="J. Rang and L. Angermann. New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1. BIT Numerical Mathematics, 45(4):761–787, 2005. doi:10.1007/s10543-005-0035-y.">RA05</a>]</span></p></td>
<td><p>4(4)</p></td>
<td><p>3(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes(3)</p></td>
<td><p>Yes</p></td>
<td><p>Yes(3)</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p>rodas3</p></td>
<td><p><span id="id3">[<a class="reference internal" href="../manualpages/TS/TSROSWSANDU3.html#id1014" title="A. Sandu, J.G. Verwer, J.G. Blom, E.J. Spee, G.R. Carmichael, and F.A. Potra. Benchmarking stiff ODE solvers for atmospheric chemistry problems II: Rosenbrock solvers. Atmospheric Environment, 31(20):3459–3472, 1997.">SVB+97</a>]</span></p></td>
<td><p>4(4)</p></td>
<td><p>3(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
<td><p>Yes</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>sandu3</p></td>
<td><p><span id="id4">[<a class="reference internal" href="../manualpages/TS/TSROSWSANDU3.html#id1014" title="A. Sandu, J.G. Verwer, J.G. Blom, E.J. Spee, G.R. Carmichael, and F.A. Potra. Benchmarking stiff ODE solvers for atmospheric chemistry problems II: Rosenbrock solvers. Atmospheric Environment, 31(20):3459–3472, 1997.">SVB+97</a>]</span></p></td>
<td><p>3(3)</p></td>
<td><p>3(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>Yes</p></td>
<td><p>Yes</p></td>
<td><p>Yes(2)</p></td>
<td><p>No</p></td>
<td><p>No</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p>assp3p3s1c</p></td>
<td><p>unpub.</p></td>
<td><p>3(2)</p></td>
<td><p>3(1)</p></td>
<td><p>A-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes</p></td>
<td><p>Yes(2)</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>SSP</p></td>
</tr>
<tr class="row-odd"><td><p>lassp3p4s2c</p></td>
<td><p>unpub.</p></td>
<td><p>4(3)</p></td>
<td><p>3(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes</p></td>
<td><p>Yes(3)</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>SSP</p></td>
</tr>
<tr class="row-even"><td><p>lassp3p4s2c</p></td>
<td><p>unpub.</p></td>
<td><p>4(3)</p></td>
<td><p>3(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes</p></td>
<td><p>Yes(3)</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>SSP</p></td>
</tr>
<tr class="row-odd"><td><p>ark3</p></td>
<td><p>unpub.</p></td>
<td><p>4(3)</p></td>
<td><p>3(1)</p></td>
<td><p>L-Stable</p></td>
<td><p>No</p></td>
<td><p>Yes</p></td>
<td><p>Yes(3)</p></td>
<td><p>Yes</p></td>
<td><p>No</p></td>
<td><p>IMEX-RK</p></td>
</tr>
</tbody>
</table>
</section>
<section id="imex-methods-for-fast-slow-systems">
<h2>IMEX Methods for fast-slow systems<a class="headerlink" href="#imex-methods-for-fast-slow-systems" title="Link to this heading">#</a></h2>
<p>Consider a fast-slow ODE system</p>
<div class="math">
\[
\begin{aligned}
\dot{u}^{slow} & = f^{slow}(t, u^{slow},u^{fast}) \\
M \dot{u}^{fast} & = g^{fast}(t, u^{slow},u^{fast}) + f^{fast}(t, u^{slow},u^{fast})
\end{aligned}
\]</div>
<p>where <span class="math">\(u^{slow}\)</span> is the slow component and <span class="math">\(u^{fast}\)</span> is the
fast component. The fast component can be partitioned additively as
described above. Thus we want to treat <span class="math">\(f^{slow}()\)</span> and
<span class="math">\(f^{fast}()\)</span> explicitly and the other terms implicitly when using
TSARKIMEX. This is achieved by using the following APIs:</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSARKIMEXSetFastSlowSplit.html">TSARKIMEXSetFastSlowSplit</a>()</span></code> informs PETSc to use ARKIMEX to solve a fast-slow system.</p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRHSSplitSetIS.html">TSRHSSplitSetIS</a>()</span></code> specifies the index set for the slow/fast components.</p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRHSSplitSetRHSFunction.html">TSRHSSplitSetRHSFunction</a>()</span></code> specifies the parts to be handled explicitly <span class="math">\(f^{slow}()\)</span> and <span class="math">\(f^{fast}()\)</span>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRHSSplitSetIFunction.html">TSRHSSplitSetIFunction</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRHSSplitSetIJacobian.html">TSRHSSplitSetIJacobian</a>()</span></code> specify the implicit part and its Jacobian.</p></li>
</ul>
<p>Note that this ODE system can also be solved by padding zeros in the implicit part and using the standard IMEX methods. However, one needs to provide the full-dimensional Jacobian whereas only a partial Jacobian is needed for the fast-slow split which is more efficient in storage and speed.</p>
</section>
<section id="glee-methods">
<h2>GLEE methods<a class="headerlink" href="#glee-methods" title="Link to this heading">#</a></h2>
<p>In this section, we describe explicit and implicit time stepping methods
with global error estimation that are introduced in
<span id="id4">[<a class="reference internal" href="#id1005" title="E.M. Constantinescu. Estimating global errors in time stepping. ArXiv e-prints, March 2016. arXiv:1503.05166.">Con16</a>]</span>. The solution vector for a
GLEE method is either [<span class="math">\(y\)</span>, <span class="math">\(\tilde{y}\)</span>] or
[<span class="math">\(y\)</span>,<span class="math">\(\varepsilon\)</span>], where <span class="math">\(y\)</span> is the solution,
<span class="math">\(\tilde{y}\)</span> is the “auxiliary solution,” and <span class="math">\(\varepsilon\)</span>
is the error. The working vector that <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE.html">TSGLEE</a></span></code> uses is <span class="math">\(Y\)</span> =
[<span class="math">\(y\)</span>,<span class="math">\(\tilde{y}\)</span>], or [<span class="math">\(y\)</span>,<span class="math">\(\varepsilon\)</span>]. A
GLEE method is defined by</p>
<ul class="simple">
<li><p><span class="math">\((p,r,s)\)</span>: (order, steps, and stages),</p></li>
<li><p><span class="math">\(\gamma\)</span>: factor representing the global error ratio,</p></li>
<li><p><span class="math">\(A, U, B, V\)</span>: method coefficients,</p></li>
<li><p><span class="math">\(S\)</span>: starting method to compute the working vector from the
solution (say at the beginning of time integration) so that
<span class="math">\(Y = Sy\)</span>,</p></li>
<li><p><span class="math">\(F\)</span>: finalizing method to compute the solution from the working
vector,<span class="math">\(y = FY\)</span>.</p></li>
<li><p><span class="math">\(F_\text{embed}\)</span>: coefficients for computing the auxiliary
solution <span class="math">\(\tilde{y}\)</span> from the working vector
(<span class="math">\(\tilde{y} = F_\text{embed} Y\)</span>),</p></li>
<li><p><span class="math">\(F_\text{error}\)</span>: coefficients to compute the estimated error
vector from the working vector
(<span class="math">\(\varepsilon = F_\text{error} Y\)</span>).</p></li>
<li><p><span class="math">\(S_\text{error}\)</span>: coefficients to initialize the auxiliary
solution (<span class="math">\(\tilde{y}\)</span> or <span class="math">\(\varepsilon\)</span>) from a specified
error vector (<span class="math">\(\varepsilon\)</span>). It is currently implemented only
for <span class="math">\(r = 2\)</span>. We have <span class="math">\(y_\text{aux} =
S_{error}[0]*\varepsilon + S_\text{error}[1]*y\)</span>, where
<span class="math">\(y_\text{aux}\)</span> is the 2nd component of the working vector
<span class="math">\(Y\)</span>.</p></li>
</ul>
<p>The methods can be described in two mathematically equivalent forms:
propagate two components (“<span class="math">\(y\tilde{y}\)</span> form”) and propagating the
solution and its estimated error (“<span class="math">\(y\varepsilon\)</span> form”). The two
forms are not explicitly specified in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE.html">TSGLEE</a></span></code>; rather, the specific
values of <span class="math">\(B, U, S, F, F_{embed}\)</span>, and <span class="math">\(F_{error}\)</span>
characterize whether the method is in <span class="math">\(y\tilde{y}\)</span> or
<span class="math">\(y\varepsilon\)</span> form.</p>
<p>The API used by this <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> method includes:</p>
<ul>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGetSolutionComponents.html">TSGetSolutionComponents</a></span></code>: Get all the solution components of the
working vector</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">ierr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/TS/TSGetSolutionComponents.html">TSGetSolutionComponents</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="kt">int</span><span class="o">*</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">*</span><span class="p">)</span>
</pre></div>
</div>
<p>Call with <code class="docutils notranslate"><span class="pre">NULL</span></code> as the last argument to get the total number of
components in the working vector <span class="math">\(Y\)</span> (this is <span class="math">\(r\)</span> (not
<span class="math">\(r-1\)</span>)), then call to get the <span class="math">\(i\)</span>-th solution component.</p>
</li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGetAuxSolution.html">TSGetAuxSolution</a></span></code>: Returns the auxiliary solution
<span class="math">\(\tilde{y}\)</span> (computed as <span class="math">\(F_\text{embed} Y\)</span>)</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">ierr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/TS/TSGetAuxSolution.html">TSGetAuxSolution</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">*</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGetTimeError.html">TSGetTimeError</a></span></code>: Returns the estimated error vector
<span class="math">\(\varepsilon\)</span> (computed as <span class="math">\(F_\text{error} Y\)</span> if
<span class="math">\(n=0\)</span> or restores the error estimate at the end of the previous
step if <span class="math">\(n=-1\)</span>)</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">ierr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/TS/TSGetTimeError.html">TSGetTimeError</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</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="o">*</span><span class="p">)</span>
</pre></div>
</div>
</li>
<li><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetTimeError.html">TSSetTimeError</a></span></code>: Initializes the auxiliary solution
(<span class="math">\(\tilde{y}\)</span> or <span class="math">\(\varepsilon\)</span>) for a specified initial
error.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">ierr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n"><a href="../manualpages/TS/TSSetTimeError.html">TSSetTimeError</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">)</span>
</pre></div>
</div>
</li>
</ul>
<p>The local error is estimated as <span class="math">\(\varepsilon(n+1)-\varepsilon(n)\)</span>.
This is to be used in the error control. The error in <span class="math">\(y\tilde{y}\)</span>
GLEE is
<span class="math">\(\varepsilon(n) = \frac{1}{1-\gamma} * (\tilde{y}(n) - y(n))\)</span>.</p>
<p>Note that <span class="math">\(y\)</span> and <span class="math">\(\tilde{y}\)</span> are reported to <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSAdapt.html">TSAdapt</a></span></code>
<code class="docutils notranslate"><span class="pre">basic</span></code> (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTBASIC.html">TSADAPTBASIC</a></span></code>), and thus it computes the local error as
<span class="math">\(\varepsilon_{loc} = (\tilde{y} -
y)\)</span>. However, the actual local error is <span class="math">\(\varepsilon_{loc}
= \varepsilon_{n+1} - \varepsilon_n = \frac{1}{1-\gamma} * [(\tilde{y} -
y)_{n+1} - (\tilde{y} - y)_n]\)</span>.</p>
<p><a class="reference internal" href="#tab-imex-glee-petsc"><span class="std std-numref">Table 16</span></a> lists currently available GL schemes with global error estimation <span id="id5">[<a class="reference internal" href="#id1005" title="E.M. Constantinescu. Estimating global errors in time stepping. ArXiv e-prints, March 2016. arXiv:1503.05166.">Con16</a>]</span>.</p>
<table class="table" id="tab-imex-glee-petsc">
<caption><span class="caption-number">Table 16 </span><span class="caption-text">GL schemes with global error estimation</span><a class="headerlink" href="#tab-imex-glee-petsc" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>TS</p></th>
<th class="head"><p>Reference</p></th>
<th class="head"><p>IM/EX</p></th>
<th class="head"><p><span class="math">\((p,r,s)\)</span></p></th>
<th class="head"><p><span class="math">\(\gamma\)</span></p></th>
<th class="head"><p>Form</p></th>
<th class="head"><p>Notes</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre">TSGLEEi1</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">BE1</span></code></p></td>
<td><p>IM</p></td>
<td><p><span class="math">\((1,3,2)\)</span></p></td>
<td><p><span class="math">\(0.5\)</span></p></td>
<td><p><span class="math">\(y\varepsilon\)</span></p></td>
<td><p>Based on backward Euler</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE23.html">TSGLEE23</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">23</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((2,3,2)\)</span></p></td>
<td><p><span class="math">\(0\)</span></p></td>
<td><p><span class="math">\(y\varepsilon\)</span></p></td>
<td></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE24.html">TSGLEE24</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">24</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((2,4,2)\)</span></p></td>
<td><p><span class="math">\(0\)</span></p></td>
<td><p><span class="math">\(y\tilde{y}\)</span></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre">TSGLEE25I</span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">25i</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((2,5,2)\)</span></p></td>
<td><p><span class="math">\(0\)</span></p></td>
<td><p><span class="math">\(y\tilde{y}\)</span></p></td>
<td></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE35.html">TSGLEE35</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">35</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((3,5,2)\)</span></p></td>
<td><p><span class="math">\(0\)</span></p></td>
<td><p><span class="math">\(y\tilde{y}\)</span></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEEEXRK2A.html">TSGLEEEXRK2A</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">exrk2a</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((2,6,2)\)</span></p></td>
<td><p><span class="math">\(0.25\)</span></p></td>
<td><p><span class="math">\(y\varepsilon\)</span></p></td>
<td></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEERK32G1.html">TSGLEERK32G1</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">rk32g1</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((3,8,2)\)</span></p></td>
<td><p><span class="math">\(0\)</span></p></td>
<td><p><span class="math">\(y\varepsilon\)</span></p></td>
<td></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEERK285EX.html">TSGLEERK285EX</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">rk285ex</span></code></p></td>
<td><p>EX</p></td>
<td><p><span class="math">\((2,9,2)\)</span></p></td>
<td><p><span class="math">\(0.25\)</span></p></td>
<td><p><span class="math">\(y\varepsilon\)</span></p></td>
<td></td>
</tr>
</tbody>
</table>
</section>
<section id="using-fully-implicit-methods">
<h2>Using fully implicit methods<a class="headerlink" href="#using-fully-implicit-methods" title="Link to this heading">#</a></h2>
<p>To use a fully implicit method like <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSTHETA.html">TSTHETA</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSBDF.html">TSBDF</a></span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSDIRK.html">TSDIRK</a></span></code>, either
provide the Jacobian of <span class="math">\(F()\)</span> (and <span class="math">\(G()\)</span> if <span class="math">\(G()\)</span> is
provided) or use a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code> that provides a coloring so the Jacobian can
be computed efficiently via finite differences.</p>
</section>
<section id="using-the-explicit-runge-kutta-timestepper-with-variable-timesteps">
<h2>Using the Explicit Runge-Kutta timestepper with variable timesteps<a class="headerlink" href="#using-the-explicit-runge-kutta-timestepper-with-variable-timesteps" title="Link to this heading">#</a></h2>
<p>The explicit Euler and Runge-Kutta methods require the ODE be in the
form</p>
<div class="math">
\[
\dot{u} = G(u,t).
\]</div>
<p>The user can either call <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a>()</span></code> and/or they can call
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a>()</span></code> (so long as the function provided to
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a>()</span></code> is equivalent to <span class="math">\(\dot{u} + \tilde{F}(t,u)\)</span>)
but the Jacobians need not be provided. <a class="footnote-reference brackets" href="#id10" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p>
<p>The Explicit Runge-Kutta timestepper with variable timesteps is an
implementation of the standard Runge-Kutta with an embedded method. The
error in each timestep is calculated using the solutions from the
Runge-Kutta method and its embedded method (the 2-norm of the difference
is used). The default method is the <span class="math">\(3\)</span>rd-order Bogacki-Shampine
method with a <span class="math">\(2\)</span>nd-order embedded method (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK3BS.html">TSRK3BS</a></span></code>). Other
available methods are the <span class="math">\(5\)</span>th-order Fehlberg RK scheme with a
<span class="math">\(4\)</span>th-order embedded method (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK5F.html">TSRK5F</a></span></code>), the
<span class="math">\(5\)</span>th-order Dormand-Prince RK scheme with a <span class="math">\(4\)</span>th-order
embedded method (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK5DP.html">TSRK5DP</a></span></code>), the <span class="math">\(5\)</span>th-order Bogacki-Shampine
RK scheme with a <span class="math">\(4\)</span>th-order embedded method (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK5BS.html">TSRK5BS</a></span></code>, and
the <span class="math">\(6\)</span>th-, <span class="math">\(7\)</span>th, and <span class="math">\(8\)</span>th-order robust Verner
RK schemes with a <span class="math">\(5\)</span>th-, <span class="math">\(6\)</span>th, and <span class="math">\(7\)</span>th-order
embedded method, respectively (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK6VR.html">TSRK6VR</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK7VR.html">TSRK7VR</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK8VR.html">TSRK8VR</a></span></code>).
Variable timesteps cannot be used with RK schemes that do not have an
embedded method (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK1FE.html">TSRK1FE</a></span></code> - <span class="math">\(1\)</span>st-order, <span class="math">\(1\)</span>-stage
forward Euler, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK2A.html">TSRK2A</a></span></code> - <span class="math">\(2\)</span>nd-order, <span class="math">\(2\)</span>-stage RK
scheme, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK3.html">TSRK3</a></span></code> - <span class="math">\(3\)</span>rd-order, <span class="math">\(3\)</span>-stage RK scheme,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK4.html">TSRK4</a></span></code> - <span class="math">\(4\)</span>-th order, <span class="math">\(4\)</span>-stage RK scheme).</p>
</section>
<section id="special-cases">
<h2>Special Cases<a class="headerlink" href="#special-cases" title="Link to this heading">#</a></h2>
<ul>
<li><p><span class="math">\(\dot{u} = A u.\)</span> First compute the matrix <span class="math">\(A\)</span> then call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetProblemType.html">TSSetProblemType</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSProblemType.html">TS_LINEAR</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="nb">NULL</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSComputeRHSFunctionLinear.html">TSComputeRHSFunctionLinear</a></span><span class="p">,</span><span class="nb">NULL</span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSComputeRHSJacobianConstant.html">TSComputeRHSJacobianConstant</a></span><span class="p">,</span><span class="nb">NULL</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/TS/TSSetProblemType.html">TSSetProblemType</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSProblemType.html">TS_LINEAR</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="nb">NULL</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSComputeIFunctionLinear.html">TSComputeIFunctionLinear</a></span><span class="p">,</span><span class="nb">NULL</span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetIJacobian.html">TSSetIJacobian</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSComputeIJacobianConstant.html">TSComputeIJacobianConstant</a></span><span class="p">,</span><span class="nb">NULL</span><span class="p">);</span>
</pre></div>
</div>
</li>
<li><p><span class="math">\(\dot{u} = A(t) u.\)</span> Use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetProblemType.html">TSSetProblemType</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSProblemType.html">TS_LINEAR</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="nb">NULL</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSComputeRHSFunctionLinear.html">TSComputeRHSFunctionLinear</a></span><span class="p">,</span><span class="nb">NULL</span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n">YourComputeRHSJacobian</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">appctx</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">YourComputeRHSJacobian()</span></code> is a function you provide that
computes <span class="math">\(A\)</span> as a function of time. Or use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetProblemType.html">TSSetProblemType</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSProblemType.html">TS_LINEAR</a></span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="nb">NULL</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSComputeIFunctionLinear.html">TSComputeIFunctionLinear</a></span><span class="p">,</span><span class="nb">NULL</span><span class="p">);</span>
<span class="n"><a href="../manualpages/TS/TSSetIJacobian.html">TSSetIJacobian</a></span><span class="p">(</span><span class="n">ts</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n">A</span><span class="p">,</span><span class="n">YourComputeIJacobian</span><span class="p">,</span><span class="w"> </span><span class="o">&amp;</span><span class="n">appctx</span><span class="p">);</span>
</pre></div>
</div>
</li>
</ul>
</section>
<section id="monitoring-and-visualizing-solutions">
<h2>Monitoring and visualizing solutions<a class="headerlink" href="#monitoring-and-visualizing-solutions" title="Link to this heading">#</a></h2>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor</span></code> - prints the time and timestep at each iteration.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_adapt_monitor</span></code> - prints information about the timestep
adaption calculation at each iteration.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_lg_timestep</span></code> - plots the size of each timestep,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorLGTimeStep.html">TSMonitorLGTimeStep</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_lg_solution</span></code> - for ODEs with only a few components
(not arising from the discretization of a PDE) plots the solution as
a function of time, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorLGSolution.html">TSMonitorLGSolution</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_lg_error</span></code> - for ODEs with only a few components plots
the error as a function of time, only if <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetSolutionFunction.html">TSSetSolutionFunction</a>()</span></code>
is provided, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorLGError.html">TSMonitorLGError</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_draw_solution</span></code> - plots the solution at each iteration,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorDrawSolution.html">TSMonitorDrawSolution</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_draw_error</span></code> - plots the error at each iteration only
if <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetSolutionFunction.html">TSSetSolutionFunction</a>()</span></code> is provided,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorDrawSolution.html">TSMonitorDrawSolution</a>()</span></code>.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_solution</span> <span class="pre">binary[:filename]</span></code> - saves the solution at each
iteration to a binary file, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorSolution.html">TSMonitorSolution</a>()</span></code>. Solution viewers work
with other time-aware formats, e.g., <code class="docutils notranslate"><span class="pre">-ts_monitor_solution</span> <span class="pre">cgns:sol.cgns</span></code>,
and can output one solution every 10 time steps by adding
<code class="docutils notranslate"><span class="pre">-ts_monitor_solution_interval</span> <span class="pre">10</span></code>. Use <code class="docutils notranslate"><span class="pre">-ts_monitor_solution_interval</span> <span class="pre">-1</span></code>
to output data only at then end of a time loop.</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor_solution_vtk</span> <span class="pre">&lt;filename-%03D.vts&gt;</span></code> - saves the solution
at each iteration to a file in vtk format,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSMonitorSolutionVTK.html">TSMonitorSolutionVTK</a>()</span></code>.</p></li>
</ul>
</section>
<section id="error-control-via-variable-time-stepping">
<h2>Error control via variable time-stepping<a class="headerlink" href="#error-control-via-variable-time-stepping" title="Link to this heading">#</a></h2>
<p>Most of the time stepping methods available in PETSc have an error
estimation and error control mechanism. This mechanism is implemented by
changing the step size in order to maintain user specified absolute and
relative tolerances. The PETSc object responsible with error control is
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSAdapt.html">TSAdapt</a></span></code>. The available <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSAdapt.html">TSAdapt</a></span></code> types are listed in the following table.</p>
<table class="table" id="tab-adaptors">
<caption><span class="caption-number">Table 17 </span><span class="caption-text"><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSAdapt.html">TSAdapt</a></span></code>: available adaptors</span><a class="headerlink" href="#tab-adaptors" title="Link to this table">#</a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>ID</p></th>
<th class="head"><p>Name</p></th>
<th class="head"><p>Notes</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTNONE.html">TSADAPTNONE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">none</span></code></p></td>
<td><p>no adaptivity</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTBASIC.html">TSADAPTBASIC</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">basic</span></code></p></td>
<td><p>the default adaptor</p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTGLEE.html">TSADAPTGLEE</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">glee</span></code></p></td>
<td><p>extension of the basic adaptor to treat <span class="math">\({\rm Tol}_{\rm A}\)</span> and <span class="math">\({\rm Tol}_{\rm R}\)</span> as separate criteria. It can also control global errors if the integrator (e.g., <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE.html">TSGLEE</a></span></code>) provides this information</p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTDSP.html">TSADAPTDSP</a></span></code></p></td>
<td><p><code class="docutils notranslate"><span class="pre">dsp</span></code></p></td>
<td><p>adaptive controller for time-stepping based on digital signal processing</p></td>
</tr>
</tbody>
</table>
<p>When using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTBASIC.html">TSADAPTBASIC</a></span></code> (the default), the user typically provides a
desired absolute <span class="math">\({\rm Tol}_{\rm A}\)</span> or a relative
<span class="math">\({\rm Tol}_{\rm R}\)</span> error tolerance by invoking
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetTolerances.html">TSSetTolerances</a>()</span></code> or at the command line with options <code class="docutils notranslate"><span class="pre">-ts_atol</span></code>
and <code class="docutils notranslate"><span class="pre">-ts_rtol</span></code>. The error estimate is based on the local truncation
error, so for every step the algorithm verifies that the estimated local
truncation error satisfies the tolerances provided by the user and
computes a new step size to be taken. For multistage methods, the local
truncation is obtained by comparing the solution <span class="math">\(y\)</span> to a lower
order <span class="math">\(\widehat{p}=p-1\)</span> approximation, <span class="math">\(\widehat{y}\)</span>, where
<span class="math">\(p\)</span> is the order of the method and <span class="math">\(\widehat{p}\)</span> the order
of <span class="math">\(\widehat{y}\)</span>.</p>
<p>The adaptive controller at step <span class="math">\(n\)</span> computes a tolerance level</p>
<div class="math">
\[
\begin{aligned}
Tol_n(i)&=&{\rm Tol}_{\rm A}(i) +  \max(y_n(i),\widehat{y}_n(i)) {\rm Tol}_{\rm R}(i)\,,\end{aligned}
\]</div>
<p>and forms the acceptable error level</p>
<div class="math">
\[
\begin{aligned}
\rm wlte_n&=& \frac{1}{m} \sum_{i=1}^{m}\sqrt{\frac{\left\|y_n(i)
  -\widehat{y}_n(i)\right\|}{Tol(i)}}\,,\end{aligned}
\]</div>
<p>where the errors are computed componentwise, <span class="math">\(m\)</span> is the dimension
of <span class="math">\(y\)</span> and <code class="docutils notranslate"><span class="pre">-ts_adapt_wnormtype</span></code> is <code class="docutils notranslate"><span class="pre">2</span></code> (default). If
<code class="docutils notranslate"><span class="pre">-ts_adapt_wnormtype</span></code> is <code class="docutils notranslate"><span class="pre">infinity</span></code> (max norm), then</p>
<div class="math">
\[
\begin{aligned}
\rm wlte_n&=& \max_{1\dots m}\frac{\left\|y_n(i)
  -\widehat{y}_n(i)\right\|}{Tol(i)}\,.\end{aligned}
\]</div>
<p>The error tolerances are satisfied when <span class="math">\(\rm wlte\le 1.0\)</span>.</p>
<p>The next step size is based on this error estimate, and determined by</p>
<div class="math" id="equation-hnew">
<span class="eqno">(5)<a class="headerlink" href="#equation-hnew" title="Permalink to this equation">#</a></span>\[
\begin{aligned}
 \Delta t_{\rm new}(t)&=&\Delta t_{\rm{old}} \min(\alpha_{\max},
 \max(\alpha_{\min}, \beta (1/\rm wlte)^\frac{1}{\widehat{p}+1}))\,,\end{aligned}
\]</div>
<p>where <span class="math">\(\alpha_{\min}=\)</span><code class="docutils notranslate"><span class="pre">-ts_adapt_clip</span></code>[0] and
<span class="math">\(\alpha_{\max}\)</span>=<code class="docutils notranslate"><span class="pre">-ts_adapt_clip</span></code>[1] keep the change in
<span class="math">\(\Delta t\)</span> to within a certain factor, and <span class="math">\(\beta&lt;1\)</span> is
chosen through <code class="docutils notranslate"><span class="pre">-ts_adapt_safety</span></code> so that there is some margin to
which the tolerances are satisfied and so that the probability of
rejection is decreased.</p>
<p>This adaptive controller works in the following way. After completing
step <span class="math">\(k\)</span>, if <span class="math">\(\rm wlte_{k+1} \le 1.0\)</span>, then the step is
accepted and the next step is modified according to
<a class="reference internal" href="#equation-hnew">(5)</a>; otherwise, the step is rejected and retaken
with the step length computed in <a class="reference internal" href="#equation-hnew">(5)</a>.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSADAPTGLEE.html">TSADAPTGLEE</a></span></code> is an extension of the basic
adaptor to treat <span class="math">\({\rm Tol}_{\rm A}\)</span> and <span class="math">\({\rm Tol}_{\rm R}\)</span>
as separate criteria. it can also control global errors if the
integrator (e.g., <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSGLEE.html">TSGLEE</a></span></code>) provides this information.</p>
</section>
<section id="handling-of-discontinuities">
<h2>Handling of discontinuities<a class="headerlink" href="#handling-of-discontinuities" title="Link to this heading">#</a></h2>
<p>For problems that involve discontinuous right-hand sides, one can set an
“event” function <span class="math">\(g(t,u)\)</span> for PETSc to detect and locate the times
of discontinuities (zeros of <span class="math">\(g(t,u)\)</span>). Events can be defined
through the event monitoring routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetEventHandler.html">TSSetEventHandler</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">nevents</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">direction</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="o">*</span><span class="n">terminate</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">indicator</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">eventP</span><span class="p">),</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">postevent</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">eventP</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">eventP</span><span class="p">);</span>
</pre></div>
</div>
<p>Here, <code class="docutils notranslate"><span class="pre">nevents</span></code> denotes the number of events, <code class="docutils notranslate"><span class="pre">direction</span></code> sets the
type of zero crossing to be detected for an event (+1 for positive
zero-crossing, -1 for negative zero-crossing, and 0 for both),
<code class="docutils notranslate"><span class="pre">terminate</span></code> conveys whether the time-stepping should continue or halt
when an event is located, <code class="docutils notranslate"><span class="pre">eventmonitor</span></code> is a user- defined routine
that specifies the event description, <code class="docutils notranslate"><span class="pre">postevent</span></code> is an optional
user-defined routine to take specific actions following an event.</p>
<p>The arguments to <code class="docutils notranslate"><span class="pre">indicator()</span></code> are the timestep context, current
time, input state <span class="math">\(u\)</span>, array of event function value, and the
(optional) user-provided context <code class="docutils notranslate"><span class="pre">eventP</span></code>.</p>
<p>The arguments to <code class="docutils notranslate"><span class="pre">postevent()</span></code> routine are the timestep context,
number of events occurred, indices of events occurred, current time, input
state <span class="math">\(u\)</span>, a boolean flag indicating forward solve (1) or adjoint
solve (0), and the (optional) user-provided context <code class="docutils notranslate"><span class="pre">eventP</span></code>.</p>
</section>
<section id="explicit-integrators-with-finite-element-mass-matrices">
<span id="sec-tchem"></span><h2>Explicit integrators with finite element mass matrices<a class="headerlink" href="#explicit-integrators-with-finite-element-mass-matrices" title="Link to this heading">#</a></h2>
<p>Discretized finite element problems often have the form <span class="math">\(M \dot u = G(t, u)\)</span> where <span class="math">\(M\)</span> is the mass matrix.
Such problems can be solved using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/DMTSSetIFunction.html">DMTSSetIFunction</a>()</span></code> with implicit integrators.
When <span class="math">\(M\)</span> is nonsingular (i.e., the problem is an ODE, not a DAE), explicit integrators can be applied to <span class="math">\(\dot u = M^{-1} G(t, u)\)</span> or <span class="math">\(\dot u = \hat M^{-1} G(t, u)\)</span>, where <span class="math">\(\hat M\)</span> is the lumped mass matrix.
While the true mass matrix generally has a dense inverse and thus must be solved iteratively, the lumped mass matrix is diagonal (e.g., computed via collocated quadrature or row sums of <span class="math">\(M\)</span>).
To have PETSc create and apply a (lumped) mass matrix automatically, first use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/DMTSSetRHSFunction.html">DMTSSetRHSFunction</a>()</span></code> to specify <span class="math">\(G\)</span> and set a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/FE/PetscFE.html">PetscFE</a></span></code> using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMAddField.html">DMAddField</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DMCreateDS.html">DMCreateDS</a>()</span></code>, then call either <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/DMTSCreateRHSMassMatrix.html">DMTSCreateRHSMassMatrix</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/DMTSCreateRHSMassMatrixLumped.html">DMTSCreateRHSMassMatrixLumped</a>()</span></code> to automatically create the mass matrix and a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> that will be used to apply <span class="math">\(M^{-1}\)</span>.
This <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> can be customized using the <code class="docutils notranslate"><span class="pre">&quot;mass_&quot;</span></code> prefix.</p>
</section>
<section id="performing-sensitivity-analysis-with-the-ts-ode-solvers">
<span id="section-sa"></span><h2>Performing sensitivity analysis with the TS ODE Solvers<a class="headerlink" href="#performing-sensitivity-analysis-with-the-ts-ode-solvers" title="Link to this heading">#</a></h2>
<p>The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> library provides a framework based on discrete adjoint models
for sensitivity analysis for ODEs and DAEs. The ODE/DAE solution process
(henceforth called the forward run) can be obtained by using either
explicit or implicit solvers in <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code>, depending on the problem
properties. Currently supported method types are <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSRK.html">TSRK</a></span></code> (Runge-Kutta)
explicit methods and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSTHETA.html">TSTHETA</a></span></code> implicit methods, which include
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSBEULER.html">TSBEULER</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSCN.html">TSCN</a></span></code>.</p>
<section id="using-the-discrete-adjoint-methods">
<h3>Using the discrete adjoint methods<a class="headerlink" href="#using-the-discrete-adjoint-methods" title="Link to this heading">#</a></h3>
<p>Consider the ODE/DAE</p>
<div class="math">
\[
F(t,y,\dot{y},p) = 0, \quad y(t_0)=y_0(p) \quad t_0 \le t \le t_F
\]</div>
<p>and the cost function(s)</p>
<div class="math">
\[
\Psi_i(y_0,p) = \Phi_i(y_F,p) + \int_{t_0}^{t_F} r_i(y(t),p,t)dt \quad i=1,...,n_\text{cost}.
\]</div>
<p>The <code class="docutils notranslate"><span class="pre">TSAdjoint</span></code> routines of PETSc provide</p>
<div class="math">
\[
\frac{\partial \Psi_i}{\partial y_0} = \lambda_i
\]</div>
<p>and</p>
<div class="math">
\[
\frac{\partial \Psi_i}{\partial p} = \mu_i + \lambda_i (\frac{\partial y_0}{\partial p}).
\]</div>
<p>To perform the discrete adjoint sensitivity analysis one first sets up
the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> object for a regular forward run but with one extra function
call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetSaveTrajectory.html">TSSetSaveTrajectory</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">),</span>
</pre></div>
</div>
<p>then calls <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSolve.html">TSSolve</a>()</span></code> in the usual manner.</p>
<p>One must create two arrays of <span class="math">\(n_\text{cost}\)</span> vectors
<span class="math">\(\lambda\)</span> and <span class="math">\(\mu\)</span> (if there are no parameters <span class="math">\(p\)</span>
then one can use <code class="docutils notranslate"><span class="pre">NULL</span></code> for the <span class="math">\(\mu\)</span> array.) The
<span class="math">\(\lambda\)</span> vectors are the same dimension and parallel layout as
the solution vector for the ODE, the <span class="math">\(\mu\)</span> vectors are of dimension
<span class="math">\(p\)</span>; when <span class="math">\(p\)</span> is small usually all its elements are on the
first MPI process, while the vectors have no entries on the other
processes. <span class="math">\(\lambda_i\)</span> and <span class="math">\(\mu_i\)</span> should be initialized with
the values <span class="math">\(d\Phi_i/dy|_{t=t_F}\)</span> and <span class="math">\(d\Phi_i/dp|_{t=t_F}\)</span>
respectively. Then one calls</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sensitivity/TSSetCostGradients.html">TSSetCostGradients</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">numcost</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="o">*</span><span class="n">lambda</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">mu</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">numcost</span></code> denotes <span class="math">\(n_\text{cost}\)</span>.
If <span class="math">\(F()\)</span> is a function of <span class="math">\(p\)</span> one needs to also provide the
Jacobian <span class="math">\(-F_p\)</span> with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sensitivity/TSSetRHSJacobianP.html">TSSetRHSJacobianP</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Amat</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">fp</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sensitivity/TSSetIJacobianP.html">TSSetIJacobianP</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Amat</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">fp</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
</pre></div>
</div>
<p>or both, depending on which form is used to define the ODE.</p>
<p>The arguments for the function <code class="docutils notranslate"><span class="pre">fp()</span></code> are the timestep context,
current time, <span class="math">\(y\)</span>, and the (optional) user-provided context.</p>
<p>If there is an integral term in the cost function, i.e. <span class="math">\(r\)</span> is
nonzero, it can be transformed into another ODE that is augmented to the
original ODE. To evaluate the integral, one needs to create a child
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> objective by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sensitivity/TSCreateQuadratureTS.html">TSCreateQuadratureTS</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscBool.html">PetscBool</a></span><span class="w"> </span><span class="n">fwd</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="o">*</span><span class="n">quadts</span><span class="p">);</span>
</pre></div>
</div>
<p>and provide the ODE RHS function (which evaluates the integrand
<span class="math">\(r\)</span>) with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">quadts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">R</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">rf</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
</pre></div>
</div>
<p>Similar to the settings for the original ODE, Jacobians of the integrand
can be provided with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">quadts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">DRDU</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">DRDU</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">drdyf</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">*</span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
<span class="n"><a href="../manualpages/Sensitivity/TSSetRHSJacobianP.html">TSSetRHSJacobianP</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">quadts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">DRDU</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">DRDU</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">drdyp</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">*</span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ctx</span><span class="p">)</span>
</pre></div>
</div>
<p>where <span class="math">\(\mathrm{drdyf}= dr /dy\)</span>, <span class="math">\(\mathrm{drdpf} = dr /dp\)</span>.
Since the integral term is additive to the cost function, its gradient
information will be included in <span class="math">\(\lambda\)</span> and <span class="math">\(\mu\)</span>.</p>
<p>Lastly, one starts the backward run by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sensitivity/TSAdjointSolve.html">TSAdjointSolve</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">).</span>
</pre></div>
</div>
<p>One can obtain the value of the integral term by calling</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sensitivity/TSGetCostIntegral.html">TSGetCostIntegral</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</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">q</span><span class="p">).</span>
</pre></div>
</div>
<p>or accessing directly the solution vector used by <code class="docutils notranslate"><span class="pre">quadts</span></code>.</p>
<p>The second argument of <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sensitivity/TSCreateQuadratureTS.html">TSCreateQuadratureTS</a>()</span></code> allows one to choose
if the integral term is evaluated in the forward run (inside
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSolve.html">TSSolve</a>()</span></code>) or in the backward run (inside <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sensitivity/TSAdjointSolve.html">TSAdjointSolve</a>()</span></code>) when
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sensitivity/TSSetCostGradients.html">TSSetCostGradients</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sensitivity/TSSetCostIntegrand.html">TSSetCostIntegrand</a>()</span></code> are called before
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSolve.html">TSSolve</a>()</span></code>. Note that this also allows for evaluating the integral
without having to use the adjoint solvers.</p>
<p>To provide a better understanding of the use of the adjoint solvers, we
introduce a simple example, corresponding to
<a href="../src/ts/tutorials/power_grid/ex3sa.c.html">TS Power Grid Tutorial ex3sa</a>.
The problem is to study dynamic security of power system when there are
credible contingencies such as short-circuits or loss of generators,
transmission lines, or loads. The dynamic security constraints are
incorporated as equality constraints in the form of discretized
differential equations and inequality constraints for bounds on the
trajectory. The governing ODE system is</p>
<div class="math">
\[
\begin{aligned}
    \phi' &= &\omega_B (\omega - \omega_S)  \\
    2H/\omega_S \, \omega' & =& p_m - p_{max} sin(\phi) -D (\omega - \omega_S), \quad t_0 \leq t \leq t_F,\end{aligned}
\]</div>
<p>where <span class="math">\(\phi\)</span> is the phase angle and <span class="math">\(\omega\)</span> is the
frequency.</p>
<p>The initial conditions at time <span class="math">\(t_0\)</span> are</p>
<div class="math">
\[
\begin{aligned}
\phi(t_0) &=& \arcsin \left( p_m / p_{max} \right), \\
w(t_0) & =& 1.\end{aligned}
\]</div>
<p><span class="math">\(p_{max}\)</span> is a positive number when the system operates normally.
At an event such as fault incidence/removal, <span class="math">\(p_{max}\)</span> will change
to <span class="math">\(0\)</span> temporarily and back to the original value after the fault
is fixed. The objective is to maximize <span class="math">\(p_m\)</span> subject to the above
ODE constraints and <span class="math">\(\phi&lt;\phi_S\)</span> during all times. To accommodate
the inequality constraint, we want to compute the sensitivity of the
cost function</p>
<div class="math">
\[
\Psi(p_m,\phi) = -p_m + c \int_{t_0}^{t_F} \left( \max(0, \phi - \phi_S ) \right)^2 dt
\]</div>
<p>with respect to the parameter <span class="math">\(p_m\)</span>. <span class="math">\(numcost\)</span> is <span class="math">\(1\)</span>
since it is a scalar function.</p>
<p>For ODE solution, PETSc requires user-provided functions to evaluate the
system <span class="math">\(F(t,y,\dot{y},p)\)</span> (set by <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIFunction.html">TSSetIFunction</a>()</span></code> ) and its
corresponding Jacobian <span class="math">\(F_y + \sigma F_{\dot y}\)</span> (set by
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSSetIJacobian.html">TSSetIJacobian</a>()</span></code>). Note that the solution state <span class="math">\(y\)</span> is
<span class="math">\([ \phi \;  \omega ]^T\)</span> here. For sensitivity analysis, we need to
provide a routine to compute <span class="math">\(\mathrm{f}_p=[0 \; 1]^T\)</span> using
<code class="docutils notranslate"><span class="pre">TSASetRHSJacobianP()</span></code>, and three routines corresponding to the
integrand <span class="math">\(r=c \left( \max(0, \phi - \phi_S ) \right)^2\)</span>,
<span class="math">\(r_p = [0 \; 0]^T\)</span> and
<span class="math">\(r_y= [ 2 c \left( \max(0, \phi - \phi_S ) \right) \; 0]^T\)</span> using
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sensitivity/TSSetCostIntegrand.html">TSSetCostIntegrand</a>()</span></code>.</p>
<p>In the adjoint run, <span class="math">\(\lambda\)</span> and <span class="math">\(\mu\)</span> are initialized as
<span class="math">\([ 0 \;  0 ]^T\)</span> and <span class="math">\([-1]\)</span> at the final time <span class="math">\(t_F\)</span>.
After <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sensitivity/TSAdjointSolve.html">TSAdjointSolve</a>()</span></code>, the sensitivity of the cost function w.r.t.
initial conditions is given by the sensitivity variable <span class="math">\(\lambda\)</span>
(at time <span class="math">\(t_0\)</span>) directly. And the sensitivity of the cost function
w.r.t. the parameter <span class="math">\(p_m\)</span> can be computed (by users) as</p>
<div class="math">
\[
\frac{\mathrm{d} \Psi}{\mathrm{d} p_m} = \mu(t_0) + \lambda(t_0)  \frac{\mathrm{d} \left[ \phi(t_0) \; \omega(t_0) \right]^T}{\mathrm{d} p_m}  .
\]</div>
<p>For explicit methods where one does not need to provide the Jacobian
<span class="math">\(F_u\)</span> for the forward solve one still does need it for the
backward solve and thus must call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Amat</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Pmat</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">f</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">fP</span><span class="p">);</span>
</pre></div>
</div>
<p>Examples include:</p>
<ul class="simple">
<li><p>discrete adjoint sensitivity using explicit and implicit time stepping methods for an ODE problem
<a href="../src/ts/tutorials/ex20adj.c.html">TS Tutorial ex20adj</a>,</p></li>
<li><p>an optimization problem using the discrete adjoint models of the ERK (for nonstiff ODEs)
and the Theta methods (for stiff DAEs)
<a href="../src/ts/tutorials/ex20opt_ic.c.html">TS Tutorial ex20opt_ic</a>
and
<a href="../src/ts/tutorials/ex20opt_p.c.html">TS Tutorial ex20opt_p</a>,</p></li>
<li><p>an ODE-constrained optimization using the discrete adjoint models of the
Theta methods for cost function with an integral term
<a href="../src/ts/tutorials/power_grid/ex3opt.c.html">TS Power Grid Tutorial ex3opt</a>,</p></li>
<li><p>discrete adjoint sensitivity using the Crank-Nicolson methods for DAEs with discontinuities
<a href="../src/ts/tutorials/power_grid/stability_9bus/ex9busadj.c.html">TS Power Grid Stability Tutorial ex9busadj</a>,</p></li>
<li><p>a DAE-constrained optimization problem using the discrete adjoint models of the Crank-Nicolson
methods for cost function with an integral term
<a href="../src/ts/tutorials/power_grid/stability_9bus/ex9busopt.c.html">TS Power Grid Tutorial ex9busopt</a>,</p></li>
<li><p>discrete adjoint sensitivity using the Crank-Nicolson methods for a PDE problem
<a href="../src/ts/tutorials/advection-diffusion-reaction/ex5adj.c.html">TS Advection-Diffusion-Reaction Tutorial ex5adj</a>.</p></li>
</ul>
</section>
<section id="checkpointing">
<h3>Checkpointing<a class="headerlink" href="#checkpointing" title="Link to this heading">#</a></h3>
<p>The discrete adjoint model requires the states (and stage values in the
context of multistage timestepping methods) to evaluate the Jacobian
matrices during the adjoint (backward) run. By default, PETSc stores the
whole trajectory to disk as binary files, each of which contains the
information for a single time step including state, time, and stage
values (optional). One can also make PETSc store the trajectory to
memory with the option <code class="docutils notranslate"><span class="pre">-ts_trajectory_type</span> <span class="pre">memory</span></code>. However, there
might not be sufficient memory capacity especially for large-scale
problems and long-time integration.</p>
<p>A so-called checkpointing scheme is needed to solve this problem. The
scheme stores checkpoints at selective time steps and recomputes the
missing information. The <code class="docutils notranslate"><span class="pre">revolve</span></code> library is used by PETSc
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSTrajectory.html">TSTrajectory</a></span></code> to generate an optimal checkpointing schedule that
minimizes the recomputations given a limited number of available
checkpoints. One can specify the number of available checkpoints with
the option
<code class="docutils notranslate"><span class="pre">-ts_trajectory_max_cps_ram</span> <span class="pre">[maximum</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">checkpoints</span> <span class="pre">in</span> <span class="pre">RAM]</span></code>.
Note that one checkpoint corresponds to one time step.</p>
<p>The <code class="docutils notranslate"><span class="pre">revolve</span></code> library also provides an optimal multistage
checkpointing scheme that uses both RAM and disk for storage. This
scheme is automatically chosen if one uses both the option
<code class="docutils notranslate"><span class="pre">-ts_trajectory_max_cps_ram</span> <span class="pre">[maximum</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">checkpoints</span> <span class="pre">in</span> <span class="pre">RAM]</span></code>
and the option
<code class="docutils notranslate"><span class="pre">-ts_trajectory_max_cps_disk</span> <span class="pre">[maximum</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">checkpoints</span> <span class="pre">on</span> <span class="pre">disk]</span></code>.</p>
<p>Some other useful options are listed below.</p>
<ul class="simple">
<li><p><code class="docutils notranslate"><span class="pre">-ts_trajectory_view</span></code> prints the total number of recomputations,</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_monitor</span></code> and <code class="docutils notranslate"><span class="pre">-ts_adjoint_monitor</span></code> allow users to monitor
the progress of the adjoint work flow,</p></li>
<li><p><code class="docutils notranslate"><span class="pre">-ts_trajectory_type</span> <span class="pre">visualization</span></code> may be used to save the whole
trajectory for visualization. It stores the solution and the time,
but no stage values. The binary files generated can be read into
MATLAB via the script
<code class="docutils notranslate"><span class="pre">$PETSC_DIR/share/petsc/matlab/PetscReadBinaryTrajectory.m</span></code>.</p></li>
</ul>
</section>
</section>
<section id="using-sundials-from-petsc">
<span id="sec-sundials"></span><h2>Using Sundials from PETSc<a class="headerlink" href="#using-sundials-from-petsc" title="Link to this heading">#</a></h2>
<p>Sundials is a parallel ODE solver developed by Hindmarsh et al. at LLNL.
The <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> library provides an interface to use the CVODE component of
Sundials directly from PETSc. (To configure PETSc to use Sundials, see
the installation guide, <code class="docutils notranslate"><span class="pre">installation/index.htm</span></code>.)</p>
<p>To use the Sundials integrators, call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetType.html">TSSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/TS/TSType.html">TSType</a></span><span class="w"> </span><span class="n"><a href="../manualpages/TS/TSSUNDIALS.html">TSSUNDIALS</a></span><span class="p">);</span>
</pre></div>
</div>
<p>or use the command line option <code class="docutils notranslate"><span class="pre">-ts_type</span></code> <code class="docutils notranslate"><span class="pre">sundials</span></code>.</p>
<p>Sundials’ CVODE solver comes with two main integrator families, Adams
and BDF (backward differentiation formula). One can select these with</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSundialsSetType.html">TSSundialsSetType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n">TSSundialsLmmType</span><span class="w"> </span><span class="p">[</span><span class="n">SUNDIALS_ADAMS</span><span class="p">,</span><span class="n">SUNDIALS_BDF</span><span class="p">]);</span>
</pre></div>
</div>
<p>or the command line option <code class="docutils notranslate"><span class="pre">-ts_sundials_type</span> <span class="pre">&lt;adams,bdf&gt;</span></code>. BDF is the
default.</p>
<p>Sundials does not use the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code> library within PETSc for its
nonlinear solvers, so one cannot change the nonlinear solver options via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>. Rather, Sundials uses the preconditioners within the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code>
package of PETSc, which can be accessed via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSundialsGetPC.html">TSSundialsGetPC</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/PC/PC.html">PC</a></span><span class="w"> </span><span class="o">*</span><span class="n">pc</span><span class="p">);</span>
</pre></div>
</div>
<p>The user can then directly set preconditioner options; alternatively,
the usual runtime options can be employed via <code class="docutils notranslate"><span class="pre">-pc_xxx</span></code>.</p>
<p>Finally, one can set the Sundials tolerances via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSundialsSetTolerance.html">TSSundialsSetTolerance</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="kt">double</span><span class="w"> </span><span class="n">abs</span><span class="p">,</span><span class="kt">double</span><span class="w"> </span><span class="n">rel</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">abs</span></code> denotes the absolute tolerance and <code class="docutils notranslate"><span class="pre">rel</span></code> the relative
tolerance.</p>
<p>Other PETSc-Sundials options include</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSundialsSetGramSchmidtType.html">TSSundialsSetGramSchmidtType</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n">TSSundialsGramSchmidtType</span><span class="w"> </span><span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>where <code class="docutils notranslate"><span class="pre">type</span></code> is either <code class="docutils notranslate"><span class="pre">SUNDIALS_MODIFIED_GS</span></code> or
<code class="docutils notranslate"><span class="pre">SUNDIALS_UNMODIFIED_GS</span></code>. This may be set via the options data base
with <code class="docutils notranslate"><span class="pre">-ts_sundials_gramschmidt_type</span> <span class="pre">&lt;modifed,unmodified&gt;</span></code>.</p>
<p>The routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSundialsSetMaxl.html">TSSundialsSetMaxl</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">restart</span><span class="p">);</span>
</pre></div>
</div>
<p>sets the number of vectors in the Krylov subpspace used by GMRES. This
may be set in the options database with <code class="docutils notranslate"><span class="pre">-ts_sundials_maxl</span></code> <code class="docutils notranslate"><span class="pre">maxl</span></code>.</p>
</section>
<section id="using-tchem-from-petsc">
<h2>Using TChem from PETSc<a class="headerlink" href="#using-tchem-from-petsc" title="Link to this heading">#</a></h2>
<p>TChem <a class="footnote-reference brackets" href="#id11" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a> is a package originally developed at Sandia National
Laboratory that can read in CHEMKIN <a class="footnote-reference brackets" href="#id12" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a> data files and compute the
right-hand side function and its Jacobian for a reaction ODE system. To
utilize PETSc’s ODE solvers for these systems, first install PETSc with
the additional <code class="docutils notranslate"><span class="pre">configure</span></code> option <code class="docutils notranslate"><span class="pre">--download-tchem</span></code>. We currently
provide two examples of its use; one for single cell reaction and one
for an “artificial” one dimensional problem with periodic boundary
conditions and diffusion of all species. The self-explanatory examples
are the
<a href="../src/ts/tutorials/extchem.c.html">The TS tutorial extchem</a>
and
<a href="../src/ts/tutorials/extchemfield.c.html">The TS tutorial extchemfield</a>.</p>
<hr></section>
</section>
<section class="tex2jax_ignore mathjax_ignore" id="solving-steady-state-problems-with-pseudo-timestepping">
<h1>Solving Steady-State Problems with Pseudo-Timestepping<a class="headerlink" href="#solving-steady-state-problems-with-pseudo-timestepping" title="Link to this heading">#</a></h1>
<p><strong>Simple Example:</strong> <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code> provides a general code for performing pseudo
timestepping with a variable timestep at each physical node point. For
example, instead of directly attacking the steady-state problem</p>
<div class="math">
\[
G(u) = 0,
\]</div>
<p>we can use pseudo-transient continuation by solving</p>
<div class="math">
\[
u_t = G(u).
\]</div>
<p>Using time differencing</p>
<div class="math">
\[
u_t \doteq \frac{{u^{n+1}} - {u^{n}} }{dt^{n}}
\]</div>
<p>with the backward Euler method, we obtain nonlinear equations at a
series of pseudo-timesteps</p>
<div class="math">
\[
\frac{1}{dt^n} B (u^{n+1} - u^{n} ) = G(u^{n+1}).
\]</div>
<p>For this problem the user must provide <span class="math">\(G(u)\)</span>, the time steps
<span class="math">\(dt^{n}\)</span> and the left-hand-side matrix <span class="math">\(B\)</span> (or optionally,
if the timestep is position independent and <span class="math">\(B\)</span> is the identity
matrix, a scalar timestep), as well as optionally the Jacobian of
<span class="math">\(G(u)\)</span>.</p>
<p>More generally, this can be applied to implicit ODE and DAE for which
the transient form is</p>
<div class="math">
\[
F(u,\dot{u}) = 0.
\]</div>
<p>For solving steady-state problems with pseudo-timestepping one proceeds
as follows.</p>
<ul>
<li><p>Provide the function <code class="docutils notranslate"><span class="pre">G(u)</span></code> with the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSFunction.html">TSSetRHSFunction</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">f</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">fP</span><span class="p">);</span>
</pre></div>
</div>
<p>The arguments to the function <code class="docutils notranslate"><span class="pre">f()</span></code> are the timestep context, the
current time, the input for the function, the output for the function
and the (optional) user-provided context variable <code class="docutils notranslate"><span class="pre">fP</span></code>.</p>
</li>
<li><p>Provide the (approximate) Jacobian matrix of <code class="docutils notranslate"><span class="pre">G(u)</span></code> and a function
to compute it at each Newton iteration. This is done with the command</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSSetRHSJacobian.html">TSSetRHSJacobian</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Amat</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="w"> </span><span class="n">Pmat</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">f</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Mat/Mat.html">Mat</a></span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">fP</span><span class="p">);</span>
</pre></div>
</div>
<p>The arguments for the function <code class="docutils notranslate"><span class="pre">f()</span></code> are the timestep context, the
current time, the location where the Jacobian is to be computed, the
(approximate) Jacobian matrix, an alternative approximate Jacobian
matrix used to construct the preconditioner, and the optional
user-provided context, passed in as <code class="docutils notranslate"><span class="pre">fP</span></code>. The user must provide the
Jacobian as a matrix; thus, if using a matrix-free approach, one must
create a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MATSHELL.html">MATSHELL</a></span></code> matrix.</p>
</li>
</ul>
<p>In addition, the user must provide a routine that computes the
pseudo-timestep. This is slightly different depending on if one is using
a constant timestep over the entire grid, or it varies with location.</p>
<ul>
<li><p>For location-independent pseudo-timestepping, one uses the routine</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSPseudoSetTimeStep.html">TSPseudoSetTimeStep</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">(</span><span class="o">*</span><span class="n">dt</span><span class="p">)(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="o">*</span><span class="p">,</span><span class="kt">void</span><span class="o">*</span><span class="p">),</span><span class="kt">void</span><span class="o">*</span><span class="w"> </span><span class="n">dtctx</span><span class="p">);</span>
</pre></div>
</div>
<p>The function <code class="docutils notranslate"><span class="pre">dt</span></code> is a user-provided function that computes the
next pseudo-timestep. As a default one can use
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TSPseudoTimeStepDefault.html">TSPseudoTimeStepDefault</a>(<a href="../manualpages/TS/TS.html">TS</a>,<a href="../manualpages/Sys/PetscReal.html">PetscReal</a>*,void*)</span></code> for <code class="docutils notranslate"><span class="pre">dt</span></code>. This
routine updates the pseudo-timestep with one of two strategies: the
default</p>
<div class="math">
\[
  dt^{n} = dt_{\mathrm{increment}}*dt^{n-1}*\frac{|| F(u^{n-1}) ||}{|| F(u^{n})||}
  \]</div>
<p>or, the alternative,</p>
<div class="math">
\[
  dt^{n} = dt_{\mathrm{increment}}*dt^{0}*\frac{|| F(u^{0}) ||}{|| F(u^{n})||}
  \]</div>
<p>which can be set with the call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSPseudoIncrementDtFromInitialDt.html">TSPseudoIncrementDtFromInitialDt</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">);</span>
</pre></div>
</div>
<p>or the option <code class="docutils notranslate"><span class="pre">-ts_pseudo_increment_dt_from_initial_dt</span></code>. The value
<span class="math">\(dt_{\mathrm{increment}}\)</span> is by default <span class="math">\(1.1\)</span>, but can be
reset with the call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/TS/TSPseudoSetTimeStepIncrement.html">TSPseudoSetTimeStepIncrement</a></span><span class="p">(</span><span class="n"><a href="../manualpages/TS/TS.html">TS</a></span><span class="w"> </span><span class="n">ts</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="w"> </span><span class="n">inc</span><span class="p">);</span>
</pre></div>
</div>
<p>or the option <code class="docutils notranslate"><span class="pre">-ts_pseudo_increment</span> <span class="pre">&lt;inc&gt;</span></code>.</p>
</li>
<li><p>For location-dependent pseudo-timestepping, the interface function
has not yet been created.</p></li>
</ul>
<div class="docutils container" id="id1">
<div role="list" class="citation-list">
<div class="citation" id="id1009" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>ARS97<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id2">1</a>,<a role="doc-backlink" href="#id9">2</a>)</span>
<p>U.M. Ascher, S.J. Ruuth, and R.J. Spiteri. Implicit-explicit Runge-Kutta methods for time-dependent partial differential equations. <em>Applied Numerical Mathematics</em>, 25:151–167, 1997.</p>
</div>
<div class="citation" id="id1010" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">AP98</a><span class="fn-bracket">]</span></span>
<p>Uri M Ascher and Linda R Petzold. <em>Computer methods for ordinary differential equations and differential-algebraic equations</em>. Volume 61. SIAM, 1998.</p>
</div>
<div class="citation" id="id1008" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">BPR11</a><span class="fn-bracket">]</span></span>
<p>S. Boscarino, L. Pareschi, and G. Russo. Implicit-explicit Runge-Kutta schemes for hyperbolic systems and kinetic equations in the diffusion limit. Arxiv preprint arXiv:1110.4375, 2011.</p>
</div>
<div class="citation" id="id1011" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">ColomesB16</a><span class="fn-bracket">]</span></span>
<p>Oriol Colomés and Santiago Badia. Segregated Runge–Kutta methods for the incompressible Navier–Stokes equations. <em>International Journal for Numerical Methods in Engineering</em>, 105(5):372–400, 2016.</p>
</div>
<div class="citation" id="id1005" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>Con16<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id4">1</a>,<a role="doc-backlink" href="#id5">2</a>)</span>
<p>E.M. Constantinescu. Estimating global errors in time stepping. <em>ArXiv e-prints</em>, March 2016. <a class="reference external" href="https://arxiv.org/abs/1503.05166">arXiv:1503.05166</a>.</p>
</div>
<div class="citation" id="id1004" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>GKC13<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id3">1</a>,<a role="doc-backlink" href="#id4">2</a>,<a role="doc-backlink" href="#id5">3</a>)</span>
<p>F.X. Giraldo, J.F. Kelly, and E.M. Constantinescu. Implicit-explicit formulations of a three-dimensional nonhydrostatic unified model of the atmosphere (NUMA). <em>SIAM Journal on Scientific Computing</em>, 35(5):B1162–B1194, 2013. <a class="reference external" href="https://doi.org/10.1137/120876034">doi:10.1137/120876034</a>.</p>
</div>
<div class="citation" id="id1007" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>KC03<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id7">1</a>,<a role="doc-backlink" href="#id10">2</a>,<a role="doc-backlink" href="#id11">3</a>)</span>
<p>C.A. Kennedy and M.H. Carpenter. Additive Runge-Kutta schemes for convection-diffusion-reaction equations. <em>Appl. Numer. Math.</em>, 44(1-2):139–181, 2003. <a class="reference external" href="https://doi.org/10.1016/S0168-9274(02)00138-1">doi:10.1016/S0168-9274(02)00138-1</a>.</p>
</div>
<div class="citation" id="id1006" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>PR05<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id6">2</a>)</span>
<p>L. Pareschi and G. Russo. Implicit-explicit Runge-Kutta schemes and applications to hyperbolic systems with relaxation. <em>Journal of Scientific Computing</em>, 25(1):129–155, 2005.</p>
</div>
<div class="citation" id="id1013" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>RA05<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>)</span>
<p>J. Rang and L. Angermann. New Rosenbrock W-methods of order 3 for partial differential algebraic equations of index 1. <em>BIT Numerical Mathematics</em>, 45(4):761–787, 2005. <a class="reference external" href="https://doi.org/10.1007/s10543-005-0035-y">doi:10.1007/s10543-005-0035-y</a>.</p>
</div>
<div class="citation" id="id1012" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>SVB+97<span class="fn-bracket">]</span></span>
<span class="backrefs">(<a role="doc-backlink" href="#id3">1</a>,<a role="doc-backlink" href="#id4">2</a>)</span>
<p>A. Sandu, J.G. Verwer, J.G. Blom, E.J. Spee, G.R. Carmichael, and F.A. Potra. Benchmarking stiff ODE solvers for atmospheric chemistry problems II: Rosenbrock solvers. <em>Atmospheric Environment</em>, 31(20):3459–3472, 1997.</p>
</div>
</div>
</div>
</section>
<hr class="footnotes docutils" />
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id9" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>
<p>If the matrix <span class="math">\(F_{\dot{u}}(t) = \partial F
/ \partial \dot{u}\)</span> is nonsingular then it is an ODE and can be
transformed to the standard explicit form, although this
transformation may not lead to efficient algorithms.</p>
</aside>
<aside class="footnote brackets" id="id10" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id6">2</a><span class="fn-bracket">]</span></span>
<p>PETSc will automatically translate the function provided to the
appropriate form.</p>
</aside>
<aside class="footnote brackets" id="id11" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id7">3</a><span class="fn-bracket">]</span></span>
<p><a class="reference external" href="https://bitbucket.org/jedbrown/tchem">bitbucket.org/jedbrown/tchem</a></p>
</aside>
<aside class="footnote brackets" id="id12" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id8">4</a><span class="fn-bracket">]</span></span>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/CHEMKIN">en.wikipedia.org/wiki/CHEMKIN</a></p>
</aside>
</aside>


                </article>
              
              
              
              
              
                <footer class="prev-next-footer">
                  
<div class="prev-next-area">
    <a class="left-prev"
       href="snes.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">SNES: Nonlinear Solvers</p>
      </div>
    </a>
    <a class="right-next"
       href="tao.html"
       title="next page">
      <div class="prev-next-info">
        <p class="prev-next-subtitle">next</p>
        <p class="prev-next-title">TAO: Optimization Solvers</p>
      </div>
      <i class="fa-solid fa-angle-right"></i>
    </a>
</div>
                </footer>
              
            </div>
            
            
              
                <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">


  <div class="sidebar-secondary-item">
<div
    id="pst-page-navigation-heading-2"
    class="page-toc tocsection onthispage">
    <i class="fa-solid fa-list"></i> On this page
  </div>
  <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
    <ul class="visible nav section-nav flex-column">
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#">TS: Scalable ODE and DAE Solvers</a><ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#basic-ts-options">Basic TS Options</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#dae-formulations">DAE Formulations</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#hessenberg-index-1-dae">Hessenberg Index-1 DAE</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#hessenberg-index-2-dae">Hessenberg Index-2 DAE</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-implicit-explicit-imex-methods">Using Implicit-Explicit (IMEX) Methods</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#imex-methods-for-fast-slow-systems">IMEX Methods for fast-slow systems</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#glee-methods">GLEE methods</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-fully-implicit-methods">Using fully implicit methods</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-the-explicit-runge-kutta-timestepper-with-variable-timesteps">Using the Explicit Runge-Kutta timestepper with variable timesteps</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#special-cases">Special Cases</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#monitoring-and-visualizing-solutions">Monitoring and visualizing solutions</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#error-control-via-variable-time-stepping">Error control via variable time-stepping</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#handling-of-discontinuities">Handling of discontinuities</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#explicit-integrators-with-finite-element-mass-matrices">Explicit integrators with finite element mass matrices</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#performing-sensitivity-analysis-with-the-ts-ode-solvers">Performing sensitivity analysis with the TS ODE Solvers</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#using-the-discrete-adjoint-methods">Using the discrete adjoint methods</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#checkpointing">Checkpointing</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-sundials-from-petsc">Using Sundials from PETSc</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#using-tchem-from-petsc">Using TChem from PETSc</a></li>
</ul>
</li>
<li class="toc-h1 nav-item toc-entry"><a class="reference internal nav-link" href="#solving-steady-state-problems-with-pseudo-timestepping">Solving Steady-State Problems with Pseudo-Timestepping</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/ts.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/ts.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>