functions.tex

利用C

\chapter{Functions}
\index{functions}
\index{Function}

\devnote{Since this chapter was written, the \texttt{Function} class has
  seen a number of improvements which are not covered here. Chapter needs
  to be updated.}

The central concept of a function on a domain $\Omega \subset \R^d$ is
modeled by the class \texttt{Function}, which is used in \dolfin{} to
represent coefficients or solutions of partial differential equations.

%------------------------------------------------------------------------------
\section{Basic properties}

The following basic properties hold for all \texttt{Function}s:
\begin{itemize}
\item
  A \texttt{Function} can be scalar or vector-valued;
\item
  A \texttt{Function} can be restricted (interpolated) to each local
  \texttt{Cell} of a \texttt{Mesh};
\item
  The underlying representation of a \texttt{Function} may vary.
\end{itemize}

Depending on the actual underlying representation of a \texttt{Function}, it
may also be possible to evaluate a \texttt{Function} at any given \texttt{Point}.

\subsection{Representation}

Currently supported representations of \texttt{Function}s include
\emph{discrete} \texttt{Function}s, \emph{user-defined}
\texttt{Function}s and \emph{constant} \texttt{Function}s. These are
discussed in detail below.

\subsection{Assignment}

One \texttt{Function} may be assigned to another \texttt{Function}:
\begin{code}
Function v;
Function u = v;
\end{code}

\subsection{Components and subfunctions}

If a \texttt{Function} is vector-valued, or in general \emph{nested}
(mixed), a new \texttt{Function} may be created to represent any given
\emph{subsystem} (component) of the original \texttt{Function}, as
illustrated by the following example:
\begin{code}
Function u;         // Function with two components
Function u0 = u[0]; // First subsystem (component) of u
Function u1 = u[1]; // First subsystem (component) of u
\end{code}

If a \texttt{Function} represents a nested function (one defined in
terms of a mixed finite element, see below), then indexing has the
effect of picking out subfunctions. With \texttt{w} a
\texttt{Function} representing the solution $w = (u, p)$ of a Stokes
or Navier-Stokes system (with $u$ the vector-valued velocity and $p$
the scalar pressure), the following example illustrates how to pick
subfunctions and components of \texttt{w}:
\begin{code}
Function w; // Mixed Function (u, p)
u = w[0];   // First subfunction (velocity)
p = w[1];   // Second subfunction (pressure)
u0 = u[0];  // First component of the velocity
u1 = u[1];  // Second component of the velocity
u2 = u[2];  // Third component of the velocity
\end{code}

\subsection{Output}
\index{ParaView}
\index{MayaVi}

A \texttt{Function} can be written to a file in various file formats.
To write a \texttt{Function}~\texttt{u} to file in VTK~format,
suitable for viewing in ParaView or MayaVi, create a file with
extension \texttt{.pvd}:
\begin{code}
File file("solution.pvd");
file << u;
\end{code}

For further details on available file formats, see
Chapter~\ref{chapter:io}.

%------------------------------------------------------------------------------
\section{Discrete functions}

A discrete \texttt{Function} is defined in terms of a
\texttt{Vector} of degrees of freedom, a \texttt{Mesh}, a
local-to-global mapping (\texttt{DofMap}) and a finite element.  In
particular, a discrete \texttt{Function} is given by a linear
combinations of basis functions:
\begin{equation}
  v = \sum_{i=1}^{N} v_i \phi_{i},
\end{equation}
where $\{\phi_i\}_{i=1}^N$ is the global basis of the finite element
space defined by the \texttt{Mesh} and the finite element, and
the nodal values $\{v_i\}_{i=1}^N$ are given by the values of a
\texttt{Vector}.

%------------------------------------------------------------------------------
\section{User-defined functions}
\index{user-defined functions}

In the simplest case, a user-defined \texttt{Function} is just an
expression in terms of the coordinates and is typically used for
defining source terms and initial conditions. For example, a source
term could be given by
\begin{equation} \label{eq:functionexample}
  f = f(x, y, z) = xy \sin(z / \pi).
\end{equation}

A user-defined \texttt{Function} may be defined by creating a sub
class of \texttt{Function} and overloading the \texttt{eval()}
function.  The following example illustrates how to create a
\texttt{Function} representing the function in
(\ref{eq:functionexample}):
\begin{code}
class Source : public Function
{
public:
    
  Source(Mesh& mesh) : Function(mesh) {}

  real eval(const real* x) const
  {
    return x[0]*x[1]*sin(x[2] / DOLFIN_PI);
  }

};

Source f;
\end{code}

\devnote{Write about how to define vector-valued functions.}

\subsection{Cell-dependent functions}

In some cases, it may be convenient to define a \texttt{Function} in
terms of properties of the current \texttt{Cell}. One such example is
a \texttt{Function} that at any given point takes the value of the
mesh size at that point.

The following example illustrates how to create such as
\texttt{Function} by overloading the \texttt{eval()} function:
\begin{code}
class MeshSize : public Function
{
public:

  MeshSize(Mesh& mesh) : Function(mesh) {}

  real eval(const real* x) const
  {
    return cell().diameter();
  }
    
};

MeshSize h;
\end{code}

Note that the current \texttt{Cell} is only available during assembly
and has no meaning otherwise. For example, it is not possible to write the
\texttt{Function}~\texttt{h} to file.

\devnote{Write about predefined special functions like
\texttt{MeshSize} and \texttt{FacetNormal}.}

\subsection{Simple definition of functions in Python}

\devnote{This is a verbatim copy from the mailing list. It should be
edited for the manual.}

\footnotesize
\begin{verbatim}
On Wed, Jun 04, 2008 at 12:44:17PM +0200, Martin Sandve Alnaes wrote:
2008/6/3 Anders Logg <[e-mail]>:
On Tue, Jun 03, 2008 at 11:23:41PM +0200, Martin Sandve Alnaes wrote:
>> It's easy with some helper functions I have, I can show you tomorrow.
>> It only depends on dolfin::Function (i.e. dolfin.cpp_Function) and Instant.
>
> ok, nice. Maybe we can add the helper functions to assemble.py.

Now you can do things like this:

A = assemble(..., coefficients=[myfunction, 1.23, "sin(x[0])"])

1.23 is wrapped in a cpp_Function (i.e. a constant Function), and
the string is compiled as a C++ dolfin::Function like "v[0] = ...;".

If you want more control over the implementation
(i.e. temporary variables in eval for efficiency, if-checks, etc.)
you can also do this:

code = """
class F: dolfin::Function {
 ...
};
class G: dolfin::Function {
 ...
};
"""

f, g = compile_functions(code, mesh)


Or, if you just want to precompile but don't need anything too fancy:

expressions = ["sin(x[0])",
                         ("a*x[1]", "b*x[0]")]
f, g = compile_functions(expressions, mesh)
assert f.rank() == 0
assert g.rank() == 1
g.a = 1.23
g.b = 3.21

Note that:
- a tuple is interpreted as a vector expression

- a tuple of tuples is interpreted as a matrix expression

- variables like a and b in the strings above are detected
  automatically, but this requires all builtin names to be
  registered in the variable dolfin.compile_functions._builtins,
  which currently contains some common mathematical
  functions like sqrt, pow, exp, sin, pi etc.

- variables are initialized to 0.0, so use compile_functions if
  you need control over variable values.

- assemble also accepts tuples like in compile_functions

- assemble only calls on instant once independently of
  the number of string expressions, to reduce compilation time

- Error checks are not extensive!
\end{verbatim}
\normalsize