1 

2 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
3 
% Copyright (c) 20032014 by University of Queensland 
4 
% http://www.uq.edu.au 
5 
% 
6 
% Primary Business: Queensland, Australia 
7 
% Licensed under the Open Software License version 3.0 
8 
% http://www.opensource.org/licenses/osl3.0.php 
9 
% 
10 
% Development until 2012 by Earth Systems Science Computational Center (ESSCC) 
11 
% Development 20122013 by School of Earth Sciences 
12 
% Development from 2014 by Centre for Geoscience Computing (GeoComp) 
13 
% 
14 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
15 

16 
\chapter{The \speckley Module}\label{CHAPTER ON SPECKLEY} 
17 
%\declaremodule{extension}{speckley} 
18 
%\modulesynopsis{Solving linear, steady partial differential equations using spectral elements} 
19 

20 
{\it speckley} is a highorder form of {\it ripley}, supporting structured, 
21 
uniform meshes in two and three dimensions. Uniform meshes allow a more regular 
22 
division of elements among compute nodes. Possible orders range from 2 to 10, 
23 
inclusive. 
24 

25 
{\it speckley} domains cannot be created by reading from a mesh file. 
26 

27 
The family of domain that will result from a 
28 
\class{Rectangle} or \class{Brick} call depends on which module is imported in 
29 
the specific script. The following line is an example of importing 
30 
\speckley domains: 
31 

32 
\begin{python} 
33 
from esys.speckley import Rectangle, Brick 
34 
\end{python} 
35 

36 
\section{Formulation} 
37 
For a single PDE that has a solution with a single component the linear PDE is 
38 
defined in the following form: 
39 
\begin{equation}\label{SPECKLEY.SINGLE.1} 
40 
\begin{array}{cl} & 
41 
\displaystyle{ 
42 
\int_{\Omega} 
43 
D \cdot vu \; d\Omega } + \int_{\Gamma} d \cdot vu \; d{\Gamma} 
44 

45 
= \displaystyle{\int_{\Omega} X_{j} \cdot v_{,j}+ Y \cdot v \; d\Omega } 
46 
+ \displaystyle{\int_{\Gamma} y \cdot v \; d{\Gamma}} 
47 
\end{array} 
48 
\end{equation} 
49 

50 
\section{Meshes} 
51 
\label{SPECKLEY MESHES} 
52 

53 
\speckley meshes are formed of regular elements using GaussLabattoLegendre 
54 
quadrature points. The number of quadrature points in each axis is dependent 
55 
on the order of the domain. Examples of small Rectangle domains of different 
56 
orders are shown in Figure~\ref{SPECKLEY:FIG:MESHES}. 
57 

58 
Meshfiles cannot be used to generate \speckley domains. 
59 

60 
\begin{figure} 
61 
\begin{center} 
62 
\subfigure[order 3]{% 
63 
\label{FIG:SPECKLEYMESH:ORDER3} 
64 
\includegraphics[width=0.3\textwidth]{speckley3} 
65 
}% 
66 
\subfigure[order 6]{% 
67 
\label{FIG:SPECKLEYMESH:ORDER6} 
68 
\includegraphics[width=0.3\textwidth]{speckley6} 
69 
}% 
70 
\subfigure[order 9]{% 
71 
\label{FIG:SPECKLEYMESH:ORDER9} 
72 
\includegraphics[width=0.3\textwidth]{speckley9} 
73 
}% 
74 
\end{center} 
75 
\caption{3x3 \emph{speckley} Rectangle domains of different orders} 
76 
\label{SPECKLEY:FIG:MESHES} 
77 
\end{figure} 
78 

79 
\section{Linear Solvers in \SolverOptions} 
80 
While \speckley has the same defaults as \ripley, the \HRZLUMPING must be set. 
81 
\PASO is not used in \speckley. 
82 

83 
\section{Crossdomain Interpolation} 
84 
Data on a \speckley domain can be interpolated to a matching \ripley domain 
85 
provided the two domains have identical dimension, length, and, in multiprocess 
86 
situations, domain subdivisions. 
87 

88 
A utility class, \class{SpeckleyToRipley} is available to simplify meeting these 
89 
conditions. To gain access to the class, the following will be required in 
90 
the script: 
91 

92 
\begin{python} 
93 
from esys.escript.domainCouplers import SpeckleyToRipley 
94 
\end{python} 
95 

96 
\section{Functions} 
97 
\begin{funcdesc}{Brick}{order,n0,n1,n2,l0=1.,l1=1.,l2=1.,d0=1,d1=1,d2=1, 
98 
diracPoints=list(), diracTags=list()} 
99 
generates a \Domain object representing a threedimensional brick between 
100 
$(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. All elements will be regular 
101 
and of order \var{order}. The brick is filled with 
102 
\var{n0} elements along the $x_0$axis, 
103 
\var{n1} elements along the $x_1$axis and 
104 
\var{n2} elements along the $x_2$axis. 
105 
If built with \MPI support, the domain will be subdivided 
106 
\var{d0} times along the $x_0$axis, 
107 
\var{d1} times along the $x_1$axis, and 
108 
\var{d2} times along the $x_2$axis. 
109 
\var{d0}, \var{d1}, and \var{d2} must be factors of the number of 
110 
\MPI processes requested. 
111 
If axial subdivisions are not specified, automatic domain subdivision will take 
112 
place. This may not be the most efficient construction and will likely result in 
113 
extra elements being added to ensure proper distribution of work. Any extra 
114 
elements added in this way will change the length of the domain proportionately. 
115 
\var{diracPoints} is a list of coordinatetuples of points within the mesh, 
116 
each point tagged with the respective string within \var{diracTags}. 
117 
\end{funcdesc} 
118 

119 
\begin{funcdesc}{Rectangle}{order,n0,n1,n2,l0=1.,l1=1.,l2=1.,d0=1,d1=1,d2=1, 
120 
diracPoints=list(), diracTags=list()} 
121 
generates a \Domain object representing a twodimensional rectangle between 
122 
$(0,0)$ and $(l0,l1)$ with orthogonal faces. All elements will be regular 
123 
and of order \var{order}. The rectangle is filled with 
124 
\var{n0} elements along the $x_0$axis and 
125 
\var{n1} elements along the $x_1$axis. 
126 
If built with \MPI support, the domain will be subdivided 
127 
\var{d0} times along the $x_0$axis and 
128 
\var{d1} times along the $x_1$axis. 
129 
\var{d0} and \var{d1} must be factors of the number of \MPI processes requested. 
130 
If axial subdivisions are not specified, automatic domain subdivision will take 
131 
place. This may not be the most efficient construction and will likely result in 
132 
extra elements being added to ensure proper distribution of work. Any extra 
133 
elements added in this way will change the length of the domain proportionately. 
134 
\var{diracPoints} is a list of coordinatetuples of points within the mesh, 
135 
each point tagged with the respective string within \var{diracTags}. 
136 
\end{funcdesc} 