doc/cookbook/example07.tex


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (c) 2003-2010 by University of Queensland
% Earth Systems Science Computational Center (ESSCC)
% http://www.uq.edu.au/esscc
%
% Primary Business: Queensland, Australia
% Licensed under the Open Software License version 3.0
% http://www.opensource.org/licenses/osl-3.0.php
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The acoustic wave equation governs the propagation of pressure waves. Wave
types that obey this law tend to travel in liquids or gases where shear waves
or longitudinal style wave motion is not possible. An obvious example is sound
waves.

The acoustic wave equation is defined as;
\begin{equation}
 \nabla ^2 p - \frac{1}{c^2} \frac{\partial ^2 p}{\partial t^2} = 0
\label{eqn:acswave}
\end{equation}
where $p$ is the pressure, $t$ is the time and $c$ is the wave velocity. In this
chapter the acoustic wave equation is demonstrated. Important steps include the
translation of the Laplacian $\nabla^2$ to the \esc general form, the stiff
equation stability criterion and solving for the displacement of acceleration solution.

\section{The Laplacian in \esc}
The Laplacian operator which can be written as $\Delta$ or $\nabla^2$  is
calculated via the divergence of the gradient of the object, which in this
example is the scalar $p$. Thus we can write;
\begin{equation}
 \nabla^2 p = \nabla \cdot \nabla p = 
    \sum_{i}^n
    \frac{\partial^2 p}{\partial x^2_{i}}
 \label{eqn:laplacian}
\end{equation}
For the two dimensional case in Cartesian coordinates \autoref{eqn:laplacian}
becomes;
\begin{equation}
 \nabla^2 p = \frac{\partial^2 p}{\partial x^2} 
           + \frac{\partial^2 p}{\partial y^2}
\end{equation}

In \esc the Laplacian is calculated using the divergence representation and the
intrinsic functions \textit{grad()} and \textit{trace()}. The function
\textit{grad{}} will return the spatial gradients of an object.  
For a rank 0 solution, this is of the form;
\begin{equation}
 \nabla p = \left[
       \frac{\partial p}{\partial x _{0}},  
       \frac{\partial p}{\partial x _{1}}
                  \right]
\label{eqn:grad}
\end{equation}
Larger ranked solution objects will return gradient tensors. For example, a
pressure field which acts in the directions $p _{0}$ and $p
_{1}$ would return;
\begin{equation}
  \nabla p = \begin{bmatrix}
       \frac{\partial p _{0}}{\partial x _{0}} &
        \frac{\partial p _{1}}{\partial x _{0}} \\
      \frac{\partial p _{0}}{\partial x _{1}} &
        \frac{\partial p _{1}}{\partial x _{1}} 
                  \end{bmatrix}
\label{eqn:gradrank1}
\end{equation}

\autoref{eqn:grad} corresponds to the Linear PDE general form value
$X$. Notice however that the general form contains the term $X
_{i,j}$\footnote{This is the first derivative in the $j^{th}$
direction for the $i^{th}$ component of the solution.},
hence for a rank 0 object there is no need to do more then calculate the
gradient and submit it to the solver. In the case of the rank 1 or greater
object, it is necessary to calculate the trace also. This is the sum of the
diagonal in \autoref{eqn:gradrank1}. 

Thus when solving for equations containing the Laplacian one of two things must
be completed. If the object \verb!p! is less then rank 1 the gradient is
calculated via;
\begin{python}
gradient=grad(p)
\end{python}
and if the object is greater then or equal to a rank 1 tensor, the trace of
the gradient is calculated.
\begin{python}
 gradient=trace(grad(p))
\end{python}
These values can then be submitted to the PDE solver via the general form term
$X$. The Laplacian is then computed in the solution process by taking the
divergence of $X$.

Note, if you are unsure about the rank of your tensor, the \textit{getRank}
command will return the rank of the PDE object.
\begin{python}
 rank = p.getRank()
\end{python}


\section{Numerical Solution Stability} \label{sec:nsstab}
Unfortunately, the wave equation belongs to a class of equations called
\textbf{stiff} PDEs. These types of equations can be difficult to solve
numerically as they tend to oscillate about the exact solution which can
eventually lead to a catastrophic failure. To counter this problem, explicitly
stable schemes like the backwards Euler method and correct parameterisation of
the problem are required. 

There are two variables which must be considered for
stability when numerically trying to solve the wave equation. For linear media,
the two variables are related via;
\begin{equation} \label{eqn:freqvel}
f=\frac{v}{\lambda}
\end{equation}
The velocity $v$ that a wave travels in a medium is an important variable. For
stability the analytical wave must not propagate faster then the numerical wave
is able to, and in general, needs to be much slower then the numerical wave.
For example, a line 100m long is discretised into 1m intervals or 101 nodes. If
a wave enters with a propagation velocity of 100m/s then the travel time for
the wave between each node will be 0.01 seconds. The time step, must therefore
be significantly less then this. Of the order $10E-4$ would be appropriate. 

The wave frequency content also plays a part in numerical stability. The
nyquist-sampling theorem states that a signals bandwidth content will be
accurately represented when an equispaced sampling rate $f _{n}$ is
equal to or greater then twice the maximum frequency of the signal
$f_{s}$, or;
\begin{equation} \label{eqn:samptheorem}
 f_{n} \geqslant f_{s}
\end{equation}
For example a 50Hz signal will require a sampling rate greater then 100Hz or
one sample every 0.01 seconds. The wave equation relies on a spatial frequency,
thus the sampling theorem in this case applies to the solution mesh spacing. In
this way, the frequency content of the input signal directly affects the time
discretisation of the problem.  

To accurately model the wave equation with high resolutions and velocities
means that very fine spatial and time discretisation is necessary for most
problems.
This requirement makes the wave equation arduous to
solve numerically due to the large number of time iterations required in each
solution. Models with very high velocities and frequencies will be the worst
affected by this problem.

\section{Displacement Solution}
\sslist{example07a.py}

We begin the solution to this PDE with the centred difference formula for the
second derivative;
\begin{equation}
 f''(x) \approx \frac{f(x+h - 2f(x) + f(x-h)}{h^2}
\label{eqn:centdiff}
\end{equation}
substituting \autoref{eqn:centdiff} for $\frac{\partial ^2 p }{\partial t ^2}$
in \autoref{eqn:acswave};
\begin{equation}
 \nabla ^2 p - \frac{1}{c^2h^2} \left[p_{(t+1)} - 2p_{(t)} +
p_{(t-1)} \right]
= 0
\label{eqn:waveu}
\end{equation}
Rearranging for $p_{(t+1)}$;
\begin{equation}
 p_{(t+1)} = c^2 h^2 \nabla ^2 p_{(t)} +2p_{(t)} -
p_{(t-1)}
\end{equation}
this can be compared with the general form of the \modLPDE module and it
becomes clear that $D=1$, $X_{i,j}=-c^2 h^2 \nabla ^2 p_{(t)}$ and
$Y=2p_{(t)} - p_{(t-1)}$.

The solution script is similar to others that we have created in previous
chapters. The general steps are;
\begin{enumerate}
 \item The necessary libraries must be imported.
 \item The domain needs to be defined.
 \item The time iteration and control parameters need to be defined.
 \item The PDE is initialised with source and boundary conditions.
 \item The time loop is started and the PDE is solved at consecutive time steps.
 \item All or select solutions are saved to file for visualisation later on.
\end{enumerate}

Parts of the script which warrant more attention are the definition of the
source, visualising the source, the solution time loop and the VTK data export.

\subsection{Pressure Sources}
As the pressure is a scalar, one need only define the pressure for two 
time steps prior to the start of the solution loop. Two known solutions are
required because the wave equation contains a double partial derivative with
respect to time. This is often a good opportunity to introduce a source to the
solution. This model has the source located at it's centre. The source should
be smooth and cover a number of samples to satisfy the frequency stability
criterion. Small sources will generate high frequency signals. Here, when using
a rectangular domain, the source is defined by a cosine function.
\begin{python}
U0=0.01 # amplitude of point source
xc=[500,500] #location of point source
# define small radius around point xc
src_radius = 30
# for first two time steps
u=U0*(cos(length(x-xc)*3.1415/src_radius)+1)*\
    whereNegative(length(x-xc)-src_radius)
u_m1=u
\end{python}

\subsection{Visualising the Source}
There are two options for visualising the source. The first is to export the
initial conditions of the model to VTK, which can be interpreted as a scalar
surface in Mayavi2. The second is to take a cross section of the model which
will require the \textit{Locator} function. 
First \verb!Locator! must be imported;
\begin{python}
 from esys.escript.pdetools import Locator
\end{python}
The function can then be used on the domain to locate the nearest domain node
to the point or points of interest.

It is now necessary to build a list of $(x,y)$ locations that specify where are
model slice will go. This is easily implemented with a loop;
\begin{python}
cut_loc=[]
src_cut=[]
for i in range(ndx/2-ndx/10,ndx/2+ndx/10):
    cut_loc.append(xstep*i)
    src_cut.append([xstep*i,xc[1]])
\end{python}
We then submit the output to \verb!Locator! and finally return the appropriate
values using the \verb!getValue! function.
\begin{python}
 src=Locator(mydomain,src_cut)
src_cut=src.getValue(u)
\end{python}
It is then a trivial task to plot and save the output using \mpl
(\autoref{fig:cxsource}).
\begin{python}
 pl.plot(cut_loc,src_cut)
pl.axis([xc[0]-src_radius*3,xc[0]+src_radius*3,0.,2*U0])
pl.savefig(os.path.join(savepath,"source_line.png"))
\end{python}
\begin{figure}[h]
 \centering
    \includegraphics[width=6in]{figures/sourceline.png}
 \caption{Cross section of the source function.}
 \label{fig:cxsource}
\end{figure}


\subsection{Point Monitoring}
In the more general case where the solution mesh is irregular or specific
locations need to be monitored, it is simple enough to use the \textit{Locator}
function. 
\begin{python}
 rec=Locator(mydomain,[250.,250.])
\end{python}
 When the solution \verb u  is updated we can extract the value at that point
via;
\begin{python}
 u_rec=rec.getValue(u)
\end{python}
For consecutive time steps one can record the values from \verb!u_rec! in an
array initialised as \verb!u_rec0=[]! with;
\begin{python}
  u_rec0.append(rec.getValue(u))
\end{python}

It can be useful to monitor the value at a single or multiple individual points
in the model during the modelling process. This is done using 
the \verb!Locator! function.


\section{Acceleration Solution}
\sslist{example07b.py}

An alternative method is to solve for the acceleration $\frac{\partial ^2
p}{\partial t^2}$ directly, and derive the displacement solution from the
PDE solution. \autoref{eqn:waveu} is thus modified;
\begin{equation}
  \nabla ^2 p - \frac{1}{c^2} a = 0
\label{eqn:wavea}
\end{equation}
and can be solved directly with $Y=0$ and $X=-c^2 \nabla ^2 p_{(t)}$.
After each iteration the displacement is re-evaluated via;
\begin{equation}
 p_{(t+1)}=2p_{(t)} - p_{(t-1)} + h^2a
\end{equation}

\subsection{Lumping}
For \esc, the acceleration solution is prefered as it allows the use of matrix
lumping. Lumping or mass lumping as it is sometimes known, is the process of
aggressively approximating the density elements of a mass matrix into the main
diagonal. The use of Lumping is motivaed by the simplicity of diagonal matrix
 inversion. As a result, Lumping can significantly reduce the computational
requirements of a problem. Care should be taken however, as this
function can only be used when the $A$, $B$ and $C$ coefficients of the
general form are zero. 

To turn lumping on in \esc one can use the command;
\begin{python}
 mypde.getSolverOptions().setSolverMethod(mypde.getSolverOptions().LUMPING)
\end{python}
It is also possible to check if lumping is set using;
\begin{python}
  print mypde.isUsingLumping()
\end{python}

\section{Stability Investigation}
It is now prudent to investigate the stability limitations of this problem.
First, we let the frequency content of the source be very small. If we define
the source as a cosine input, then the wavlength of the input is equal to the
radius of the source. Let this value be 5 meters. Now, if the maximum velocity
of the model is $c=380.0ms^{-1}$ then the source
frequency is $f_{r} = \frac{380.0}{5} = 76.0 Hz$. This is a worst case
scenario with a small source and the models maximum velocity. 

Furthermore, we know from \autoref{sec:nsstab}, that the spatial sampling
frequency must be at least twice this value to ensure stability. If we assume
the model mesh is a square equispaced grid,
then the sampling interval is the side length divided by the number of samples,
given by $\Delta x = \frac{1000.0m}{400} = 2.5m$ and the maximum sampling
frequency capable at this interval is
$f_{s}=\frac{380.0ms^{-1}}{2.5m}=152Hz$ this is just equal to the
required rate satisfying \autoref{eqn:samptheorem}. 

\autoref{fig:ex07sampth} depicts three examples where the grid has been
undersampled, sampled correctly, and over sampled. The grids used had
200, 400 and 800 nodes per side respectively. Obviously, the oversampled grid
retains the best resolution of the modelled wave.

The time step required for each of these examples is simply calculated from
the propagation requirement. For a maximum velocity of $380.0ms^{-1}$,
\begin{subequations}
 \begin{equation}
  \Delta t \leq \frac{1000.0m}{200} \frac{1}{380.0} = 0.013s
 \end{equation}
 \begin{equation}
  \Delta t \leq \frac{1000.0m}{400} \frac{1}{380.0} = 0.0065s
 \end{equation}
 \begin{equation}
  \Delta t \leq \frac{1000.0m}{800} \frac{1}{380.0} = 0.0032s
 \end{equation}
\end{subequations}
We can see, that for each doubling of the number of nodes in the mesh, we halve
the timestep. To illustrate the impact this has, consider our model. If the
source is placed at the center, it is $500m$ from the nearest boundary. With a
velocity of $380.0ms^{-1}$ it will take $\approx1.3s$ for the wavefront to
reach that boundary. In each case, this equates to $100$,  $200$ and $400$ time
steps. This is again, only a best case scenario, for true stability these time
values may need to be halved and possibly havled again.

\begin{figure}[ht]
\centering
\subfigure[Undersampled Example]{
\includegraphics[width=3in]{figures/ex07usamp.png}
\label{fig:ex07usamp}
}
\subfigure[Just sampled Example]{
\includegraphics[width=3in]{figures/ex07jsamp.png}
\label{fig:ex07jsamp}
}
\subfigure[Over sampled Example]{
\includegraphics[width=3in]{figures/ex07nsamp.png}
\label{fig:ex07nsamp}
}
\label{fig:ex07sampth}
\caption{Sampling Theorem example for stability
investigation.}
\end{figure}


1	ahallam	3003
2			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3			%
4			% Copyright (c) 2003-2010 by University of Queensland
5			% Earth Systems Science Computational Center (ESSCC)
6			% http://www.uq.edu.au/esscc
7			%
8			% Primary Business: Queensland, Australia
9			% Licensed under the Open Software License version 3.0
10			% http://www.opensource.org/licenses/osl-3.0.php
11			%
12			%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13
14
15
16			The acoustic wave equation governs the propagation of pressure waves. Wave
17			types that obey this law tend to travel in liquids or gases where shear waves
18	ahallam	3004	or longitudinal style wave motion is not possible. An obvious example is sound
19	ahallam	3003	waves.
20
21	ahallam	3004	The acoustic wave equation is defined as;
22	ahallam	3003	\begin{equation}
23			\nabla ^2 p - \frac{1}{c^2} \frac{\partial ^2 p}{\partial t^2} = 0
24			\label{eqn:acswave}
25			\end{equation}
26	ahallam	3370	where $p$ is the pressure, $t$ is the time and $c$ is the wave velocity. In this
27			chapter the acoustic wave equation is demonstrated. Important steps include the
28			translation of the Laplacian $\nabla^2$ to the \esc general form, the stiff
29			equation stability criterion and solving for the displacement of acceleration solution.
30	ahallam	3003
31	ahallam	3004	\section{The Laplacian in \esc}
32	ahallam	3370	The Laplacian operator which can be written as $\Delta$ or $\nabla^2$ is
33			calculated via the divergence of the gradient of the object, which in this
34			example is the scalar $p$. Thus we can write;
35	ahallam	3004	\begin{equation}
36	ahallam	3029	\nabla^2 p = \nabla \cdot \nabla p =
37	jfenwick	3308	\sum_{i}^n
38			\frac{\partial^2 p}{\partial x^2_{i}}
39	ahallam	3004	\label{eqn:laplacian}
40			\end{equation}
41	ahallam	3232	For the two dimensional case in Cartesian coordinates \autoref{eqn:laplacian}
42	ahallam	3004	becomes;
43			\begin{equation}
44			\nabla^2 p = \frac{\partial^2 p}{\partial x^2}
45			+ \frac{\partial^2 p}{\partial y^2}
46			\end{equation}
47	ahallam	3003
48	ahallam	3004	In \esc the Laplacian is calculated using the divergence representation and the
49	ahallam	3370	intrinsic functions \textit{grad()} and \textit{trace()}. The function
50	ahallam	3004	\textit{grad{}} will return the spatial gradients of an object.
51			For a rank 0 solution, this is of the form;
52			\begin{equation}
53			\nabla p = \left[
54	jfenwick	3308	\frac{\partial p}{\partial x _{0}},
55			\frac{\partial p}{\partial x _{1}}
56	ahallam	3004	\right]
57			\label{eqn:grad}
58			\end{equation}
59			Larger ranked solution objects will return gradient tensors. For example, a
60	jfenwick	3308	pressure field which acts in the directions $p _{0}$ and $p
61			_{1}$ would return;
62	ahallam	3004	\begin{equation}
63			\nabla p = \begin{bmatrix}
64	jfenwick	3308	\frac{\partial p _{0}}{\partial x _{0}} &
65			\frac{\partial p _{1}}{\partial x _{0}} \\
66			\frac{\partial p _{0}}{\partial x _{1}} &
67			\frac{\partial p _{1}}{\partial x _{1}}
68	ahallam	3004	\end{bmatrix}
69			\label{eqn:gradrank1}
70			\end{equation}
71	ahallam	3003
72	ahallam	3232	\autoref{eqn:grad} corresponds to the Linear PDE general form value
73	ahallam	3029	$X$. Notice however that the general form contains the term $X
74	jfenwick	3308	_{i,j}$\footnote{This is the first derivative in the $j^{th}$
75	ahallam	3029	direction for the $i^{th}$ component of the solution.},
76	ahallam	3370	hence for a rank 0 object there is no need to do more then calculate the
77	ahallam	3004	gradient and submit it to the solver. In the case of the rank 1 or greater
78	ahallam	3370	object, it is necessary to calculate the trace also. This is the sum of the
79	ahallam	3232	diagonal in \autoref{eqn:gradrank1}.
80	ahallam	3004
81			Thus when solving for equations containing the Laplacian one of two things must
82	ahallam	3370	be completed. If the object \verb!p! is less then rank 1 the gradient is
83	ahallam	3004	calculated via;
84	ahallam	3025	\begin{python}
85	ahallam	3063	gradient=grad(p)
86	ahallam	3025	\end{python}
87	ahallam	3370	and if the object is greater then or equal to a rank 1 tensor, the trace of
88	ahallam	3004	the gradient is calculated.
89	ahallam	3025	\begin{python}
90	ahallam	3004	gradient=trace(grad(p))
91	ahallam	3025	\end{python}
92	ahallam	3370	These values can then be submitted to the PDE solver via the general form term
93	ahallam	3004	$X$. The Laplacian is then computed in the solution process by taking the
94			divergence of $X$.
95
96	ahallam	3025	Note, if you are unsure about the rank of your tensor, the \textit{getRank}
97			command will return the rank of the PDE object.
98			\begin{python}
99			rank = p.getRank()
100			\end{python}
101
102
103			\section{Numerical Solution Stability} \label{sec:nsstab}
104	ahallam	3004	Unfortunately, the wave equation belongs to a class of equations called
105			\textbf{stiff} PDEs. These types of equations can be difficult to solve
106	ahallam	3370	numerically as they tend to oscillate about the exact solution which can
107			eventually lead to a catastrophic failure. To counter this problem, explicitly
108			stable schemes like the backwards Euler method and correct parameterisation of
109			the problem are required.
110
111			There are two variables which must be considered for
112			stability when numerically trying to solve the wave equation. For linear media,
113			the two variables are related via;
114	ahallam	3004	\begin{equation} \label{eqn:freqvel}
115			f=\frac{v}{\lambda}
116			\end{equation}
117	ahallam	3025	The velocity $v$ that a wave travels in a medium is an important variable. For
118	ahallam	3370	stability the analytical wave must not propagate faster then the numerical wave
119			is able to, and in general, needs to be much slower then the numerical wave.
120	ahallam	3003	For example, a line 100m long is discretised into 1m intervals or 101 nodes. If
121			a wave enters with a propagation velocity of 100m/s then the travel time for
122			the wave between each node will be 0.01 seconds. The time step, must therefore
123	ahallam	3370	be significantly less then this. Of the order $10E-4$ would be appropriate.
124	ahallam	3003
125	ahallam	3004	The wave frequency content also plays a part in numerical stability. The
126			nyquist-sampling theorem states that a signals bandwidth content will be
127	jfenwick	3308	accurately represented when an equispaced sampling rate $f _{n}$ is
128	ahallam	3370	equal to or greater then twice the maximum frequency of the signal
129	jfenwick	3308	$f_{s}$, or;
130	ahallam	3004	\begin{equation} \label{eqn:samptheorem}
131	jfenwick	3308	f_{n} \geqslant f_{s}
132	ahallam	3004	\end{equation}
133	ahallam	3370	For example a 50Hz signal will require a sampling rate greater then 100Hz or
134	ahallam	3004	one sample every 0.01 seconds. The wave equation relies on a spatial frequency,
135			thus the sampling theorem in this case applies to the solution mesh spacing. In
136			this way, the frequency content of the input signal directly affects the time
137			discretisation of the problem.
138
139			To accurately model the wave equation with high resolutions and velocities
140			means that very fine spatial and time discretisation is necessary for most
141			problems.
142			This requirement makes the wave equation arduous to
143	ahallam	3003	solve numerically due to the large number of time iterations required in each
144	ahallam	3004	solution. Models with very high velocities and frequencies will be the worst
145	ahallam	3029	affected by this problem.
146	ahallam	3003
147			\section{Displacement Solution}
148			\sslist{example07a.py}
149
150			We begin the solution to this PDE with the centred difference formula for the
151			second derivative;
152			\begin{equation}
153			f''(x) \approx \frac{f(x+h - 2f(x) + f(x-h)}{h^2}
154			\label{eqn:centdiff}
155			\end{equation}
156	ahallam	3232	substituting \autoref{eqn:centdiff} for $\frac{\partial ^2 p }{\partial t ^2}$
157			in \autoref{eqn:acswave};
158	ahallam	3003	\begin{equation}
159	jfenwick	3308	\nabla ^2 p - \frac{1}{c^2h^2} \left[p_{(t+1)} - 2p_{(t)} +
160			p_{(t-1)} \right]
161	ahallam	3003	= 0
162			\label{eqn:waveu}
163			\end{equation}
164			Rearranging for $p_{(t+1)}$;
165			\begin{equation}
166	jfenwick	3308	p_{(t+1)} = c^2 h^2 \nabla ^2 p_{(t)} +2p_{(t)} -
167			p_{(t-1)}
168	ahallam	3003	\end{equation}
169			this can be compared with the general form of the \modLPDE module and it
170	jfenwick	3308	becomes clear that $D=1$, $X_{i,j}=-c^2 h^2 \nabla ^2 p_{(t)}$ and
171	ahallam	3004	$Y=2p_{(t)} - p_{(t-1)}$.
172	ahallam	3003
173	ahallam	3025	The solution script is similar to others that we have created in previous
174	ahallam	3004	chapters. The general steps are;
175			\begin{enumerate}
176			\item The necessary libraries must be imported.
177			\item The domain needs to be defined.
178			\item The time iteration and control parameters need to be defined.
179			\item The PDE is initialised with source and boundary conditions.
180			\item The time loop is started and the PDE is solved at consecutive time steps.
181	ahallam	3370	\item All or select solutions are saved to file for visualisation later on.
182	ahallam	3004	\end{enumerate}
183
184			Parts of the script which warrant more attention are the definition of the
185			source, visualising the source, the solution time loop and the VTK data export.
186
187			\subsection{Pressure Sources}
188			As the pressure is a scalar, one need only define the pressure for two
189			time steps prior to the start of the solution loop. Two known solutions are
190			required because the wave equation contains a double partial derivative with
191			respect to time. This is often a good opportunity to introduce a source to the
192			solution. This model has the source located at it's centre. The source should
193			be smooth and cover a number of samples to satisfy the frequency stability
194	ahallam	3370	criterion. Small sources will generate high frequency signals. Here, when using
195			a rectangular domain, the source is defined by a cosine function.
196	ahallam	3025	\begin{python}
197	ahallam	3004	U0=0.01 # amplitude of point source
198			xc=[500,500] #location of point source
199			# define small radius around point xc
200			src_radius = 30
201			# for first two time steps
202	ahallam	3025	u=U0(cos(length(x-xc)3.1415/src_radius)+1)*\
203			whereNegative(length(x-xc)-src_radius)
204	ahallam	3004	u_m1=u
205	ahallam	3025	\end{python}
206	ahallam	3004
207	ahallam	3025	\subsection{Visualising the Source}
208			There are two options for visualising the source. The first is to export the
209			initial conditions of the model to VTK, which can be interpreted as a scalar
210	ahallam	3370	surface in Mayavi2. The second is to take a cross section of the model which
211			will require the \textit{Locator} function.
212	ahallam	3063	First \verb!Locator! must be imported;
213	ahallam	3025	\begin{python}
214			from esys.escript.pdetools import Locator
215			\end{python}
216			The function can then be used on the domain to locate the nearest domain node
217			to the point or points of interest.
218
219			It is now necessary to build a list of $(x,y)$ locations that specify where are
220	ahallam	3370	model slice will go. This is easily implemented with a loop;
221	ahallam	3025	\begin{python}
222			cut_loc=[]
223			src_cut=[]
224			for i in range(ndx/2-ndx/10,ndx/2+ndx/10):
225			cut_loc.append(xstep*i)
226			src_cut.append([xstep*i,xc[1]])
227			\end{python}
228	ahallam	3063	We then submit the output to \verb!Locator! and finally return the appropriate
229			values using the \verb!getValue! function.
230	ahallam	3025	\begin{python}
231			src=Locator(mydomain,src_cut)
232			src_cut=src.getValue(u)
233			\end{python}
234	ahallam	3370	It is then a trivial task to plot and save the output using \mpl
235			(\autoref{fig:cxsource}).
236	ahallam	3025	\begin{python}
237			pl.plot(cut_loc,src_cut)
238			pl.axis([xc[0]-src_radius3,xc[0]+src_radius3,0.,2*U0])
239			pl.savefig(os.path.join(savepath,"source_line.png"))
240			\end{python}
241			\begin{figure}[h]
242	ahallam	3029	\centering
243	ahallam	3063	\includegraphics[width=6in]{figures/sourceline.png}
244	ahallam	3025	\caption{Cross section of the source function.}
245			\label{fig:cxsource}
246			\end{figure}
247
248
249			\subsection{Point Monitoring}
250			In the more general case where the solution mesh is irregular or specific
251			locations need to be monitored, it is simple enough to use the \textit{Locator}
252			function.
253			\begin{python}
254			rec=Locator(mydomain,[250.,250.])
255			\end{python}
256	ahallam	3029	When the solution \verb u is updated we can extract the value at that point
257	ahallam	3025	via;
258			\begin{python}
259			u_rec=rec.getValue(u)
260			\end{python}
261	ahallam	3063	For consecutive time steps one can record the values from \verb!u_rec! in an
262			array initialised as \verb!u_rec0=[]! with;
263	ahallam	3025	\begin{python}
264			u_rec0.append(rec.getValue(u))
265			\end{python}
266
267			It can be useful to monitor the value at a single or multiple individual points
268			in the model during the modelling process. This is done using
269	ahallam	3063	the \verb!Locator! function.
270	ahallam	3025
271
272	ahallam	3003	\section{Acceleration Solution}
273			\sslist{example07b.py}
274
275			An alternative method is to solve for the acceleration $\frac{\partial ^2
276	ahallam	3029	p}{\partial t^2}$ directly, and derive the displacement solution from the
277	ahallam	3232	PDE solution. \autoref{eqn:waveu} is thus modified;
278	ahallam	3003	\begin{equation}
279			\nabla ^2 p - \frac{1}{c^2} a = 0
280			\label{eqn:wavea}
281			\end{equation}
282	jfenwick	3308	and can be solved directly with $Y=0$ and $X=-c^2 \nabla ^2 p_{(t)}$.
283	ahallam	3003	After each iteration the displacement is re-evaluated via;
284			\begin{equation}
285	jfenwick	3308	p_{(t+1)}=2p_{(t)} - p_{(t-1)} + h^2a
286	ahallam	3003	\end{equation}
287
288	ahallam	3029	\subsection{Lumping}
289	ahallam	3004	For \esc, the acceleration solution is prefered as it allows the use of matrix
290			lumping. Lumping or mass lumping as it is sometimes known, is the process of
291			aggressively approximating the density elements of a mass matrix into the main
292			diagonal. The use of Lumping is motivaed by the simplicity of diagonal matrix
293			inversion. As a result, Lumping can significantly reduce the computational
294	ahallam	3029	requirements of a problem. Care should be taken however, as this
295			function can only be used when the $A$, $B$ and $C$ coefficients of the
296			general form are zero.
297	ahallam	3003
298	ahallam	3004	To turn lumping on in \esc one can use the command;
299	ahallam	3025	\begin{python}
300	ahallam	3004	mypde.getSolverOptions().setSolverMethod(mypde.getSolverOptions().LUMPING)
301	ahallam	3025	\end{python}
302	ahallam	3004	It is also possible to check if lumping is set using;
303	ahallam	3025	\begin{python}
304	ahallam	3004	print mypde.isUsingLumping()
305	ahallam	3025	\end{python}
306	ahallam	3004
307			\section{Stability Investigation}
308			It is now prudent to investigate the stability limitations of this problem.
309	ahallam	3025	First, we let the frequency content of the source be very small. If we define
310	ahallam	3370	the source as a cosine input, then the wavlength of the input is equal to the
311	ahallam	3025	radius of the source. Let this value be 5 meters. Now, if the maximum velocity
312			of the model is $c=380.0ms^{-1}$ then the source
313	jfenwick	3308	frequency is $f_{r} = \frac{380.0}{5} = 76.0 Hz$. This is a worst case
314	ahallam	3025	scenario with a small source and the models maximum velocity.
315
316	ahallam	3232	Furthermore, we know from \autoref{sec:nsstab}, that the spatial sampling
317	ahallam	3025	frequency must be at least twice this value to ensure stability. If we assume
318			the model mesh is a square equispaced grid,
319			then the sampling interval is the side length divided by the number of samples,
320			given by $\Delta x = \frac{1000.0m}{400} = 2.5m$ and the maximum sampling
321			frequency capable at this interval is
322	jfenwick	3308	$f_{s}=\frac{380.0ms^{-1}}{2.5m}=152Hz$ this is just equal to the
323	ahallam	3232	required rate satisfying \autoref{eqn:samptheorem}.
324	ahallam	3004
325	ahallam	3232	\autoref{fig:ex07sampth} depicts three examples where the grid has been
326	ahallam	3025	undersampled, sampled correctly, and over sampled. The grids used had
327			200, 400 and 800 nodes per side respectively. Obviously, the oversampled grid
328			retains the best resolution of the modelled wave.
329	ahallam	3004
330	ahallam	3025	The time step required for each of these examples is simply calculated from
331			the propagation requirement. For a maximum velocity of $380.0ms^{-1}$,
332			\begin{subequations}
333			\begin{equation}
334			\Delta t \leq \frac{1000.0m}{200} \frac{1}{380.0} = 0.013s
335			\end{equation}
336			\begin{equation}
337			\Delta t \leq \frac{1000.0m}{400} \frac{1}{380.0} = 0.0065s
338			\end{equation}
339			\begin{equation}
340			\Delta t \leq \frac{1000.0m}{800} \frac{1}{380.0} = 0.0032s
341			\end{equation}
342			\end{subequations}
343			We can see, that for each doubling of the number of nodes in the mesh, we halve
344			the timestep. To illustrate the impact this has, consider our model. If the
345			source is placed at the center, it is $500m$ from the nearest boundary. With a
346			velocity of $380.0ms^{-1}$ it will take $\approx1.3s$ for the wavefront to
347			reach that boundary. In each case, this equates to $100$, $200$ and $400$ time
348			steps. This is again, only a best case scenario, for true stability these time
349			values may need to be halved and possibly havled again.
350	ahallam	3004
351	ahallam	3025	\begin{figure}[ht]
352			\centering
353			\subfigure[Undersampled Example]{
354	ahallam	3054	\includegraphics[width=3in]{figures/ex07usamp.png}
355	ahallam	3025	\label{fig:ex07usamp}
356			}
357			\subfigure[Just sampled Example]{
358	ahallam	3054	\includegraphics[width=3in]{figures/ex07jsamp.png}
359	ahallam	3025	\label{fig:ex07jsamp}
360			}
361			\subfigure[Over sampled Example]{
362	ahallam	3054	\includegraphics[width=3in]{figures/ex07nsamp.png}
363	ahallam	3025	\label{fig:ex07nsamp}
364			}
365			\label{fig:ex07sampth}
366			\caption{Sampling Theorem example for stability
367			investigation.}
368			\end{figure}
369	ahallam	3004
370	ahallam	3025
371
372
373