% $Id: developers.tex,v 1.18 2000/09/22 21:35:11 balay Exp $
%
% LATEX version of the PETSc users manual.
%
% manual_tex.tex is the base file for LaTeX format, while manual.tex is
% the corresponding base HTML format file.
%
\documentclass[twoside,12pt]{../sty/report_petsc}

\usepackage{makeidx,xspace}
\usepackage[bookmarksopen,colorlinks]{hyperref}
\usepackage[all]{hypcap}
\usepackage{color}
\input pdfcolor.tex

\usepackage[pdftex]{graphicx}
\usepackage{../sty/verbatim}
\usepackage{../sty/tpage}
\usepackage{../sty/here}
\usepackage{../sty/anlhelper}
\usepackage[obeyspaces]{../sty/trl}

\setlength{\textwidth}{6.5in}
\setlength{\oddsidemargin}{0.0in}
\setlength{\evensidemargin}{0.0in}
\setlength{\textheight}{9.2in}
\setlength{\topmargin}{-.8in}

\newcommand{\findex}[1]{\index{FUNCTION #1}}
\newcommand{\sindex}[1]{\index{#1}}
\newcommand{\F}{\mbox{\boldmath \(F\)}}
\newcommand{\x}{\mbox{\boldmath \(x\)}}
\newcommand{\vu}{\mbox{\boldmath \(u\)}}
\newcommand{\rr}{\mbox{\boldmath \(r\)}}

\makeindex


\begin{document}

\ANLTitle{PETSc Developers Manual}{\em The PETSc Team \\
http://www.mcs.anl.gov/petsc
\vspace{0.5in} \\
{\rm This document is intended for use with PETSc 3.0}}
{}{2008}

\newpage

\hbox{ }

\vspace{1in}
\date{\today}

% Blank page makes double sided printout look bettter.
\newpage

\chapter{Characteristics and Semi-Lagrangian Integration}
\label{chapter_characteristics}
\sindex{characteristics}

    Semi-Lagrangian integration is a particular use of the method of characteristics to discretize the total time
derviative of a given field. Traditionally, we have
\begin{equation}
  {D\phi(\x) \over dt} = {\partial\phi(\x) \over \partial t} + {\partial\x \over \partial t} \cdot \nabla\phi
  = {\partial\phi(\x) \over \partial t} + \vu \cdot \nabla\phi(\x)
\end{equation}
the familiar material derivative. Alternatively, we may express this derivative as
\begin{equation}
  {D\phi(\x,t) \over dt} \cong {\phi(\x,t^{n+1}) - \phi^*(\x,t^n)\over \Delta t}
\end{equation}
where $\phi^*$ indicates the field at the previous time, but advected along the characteristics to the present time. If
we think of a flowing fluid, we want to compare the same two small chunks of fluid at times $t^{n+1}$ and $t^n$. We do
this by taking the field $\phi(t^n)$ and pushing it along the characteristics to time $t^{n+1}$. In order to do this, we
also need a velocity field for $\phi$, which may be caluclated automatically or specified.

    PETSc implements this algorithms using the Characteristic class, which is currently restricted to treating fields
represented on a DA, but will be extended to include any DM in the future. We begin by creating a context
\begin{tabbing}
  CharacteristicCreate(comm, \&c);
\end{tabbing}
and then by specifying an interpolation prescription for both the field and its velocity.
\begin{tabbing}
  numComp = 2; daComp[0] = 0; daComp[1] = 1; \\
  CharacteristicSetVelocityInterpolationLocal(\=c, da, V, Vold, numVelComp, daComponents,\\
                                              \>InterpVelocity2D, ctx); \\
  numComp = 1; daComp[0] = 2; \\
  CharacteristicSetFieldInterpolationLocal(\=c, da, Phi, numComp, daComponents,\\
                                           \>InterpFields2D, ctx);
\end{tabbing}
We need to specify the DM and a work vector on it, the number of field (velocity) components and the DM component
numbers for them, and finally an interpolation function and user context. In the example above, we use a single DM which
holds the field velocity in the first two DM components, and the field in the third. The interpolation function accepts
the field as a multidimensional array from the DM along with a real (i,j) in the grid, and returns the field values. The
main operation of advection is accomplished using
\begin{tabbing}
  CharacteristicSolve(c, dt, PhiStar);
\end{tabbing}
which takes the initial values in the vector Phi, and the velocities in V, and advects the field into PhiStar. The user
is responsible for managing the data in various vectors across timesteps.

    Since we have a generic advection routine, we can advect any field that can exist on a DA. For instance, in
Characteristic example 4, we discretize the advection-diffusion equation
\begin{equation}
  {Du\over dt} - \nabla^2 u = 0
\end{equation}
using the Crank-Nicholson scheme
\begin{equation}
  {u^+ - u^* \over \Delta t} - {1\over2} \left( (\nabla^2 u)^+ + (\nabla^2 u)^* \right) = 0
\end{equation}
which becomes after collecting terms
\begin{equation}
  u^+ -  {\Delta t\over 2} (\nabla^2 u)^+ = u^* + {\Delta t\over 2} (\nabla^2 u)^* = 0
\end{equation}
where $+$ indicates the new time, and $*$ indicates the old field advected to the new time. Thus, we advect the entire
field
\begin{equation}
  \left( I + {\Delta t\over 2} \nabla^2 \right) u,
\end{equation}
and then solve
\begin{equation}
  u^+ = \left( I - {\Delta t\over 2} \nabla^2 \right)^{-1} \left( u + {\Delta t\over 2} \nabla^2 u \right)^*.
\end{equation}

Our implementation for the DM uses the midpoint method to integrate along a characteristic. First, the velocity field at
the current time is used to find the positions at time $t^{n-1/2}$ of each field point. Some of these points will lie on
other processes and are thus communicated. Next, the velocity field for time $t^{n-1/2}$ is calculated on these points
using the trapezoid rule for times $t^n$ and $t^{n-1}$ and this result communicated back to the original point
owners. Then the full timestep is taken using the midpoint velocity, where again offprocessor positions are
communicated. Finally, the field $\phi$ is evaluated on these positions at $t^{n-1}$ and communicated to the original
owners. This final field is $\phi^*$.


\bibliographystyle{plain}
\bibliography{../petsc}

\end{document}
