# Contents of /trunk/doc/user/speckley.tex

Revision 5279 - (show annotations)
Thu Nov 27 00:26:18 2014 UTC (4 years, 9 months ago) by sshaw
File MIME type: application/x-tex
File size: 5770 byte(s)
adding ripley and speckley to user guide, a bit barebones still

 1 2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 3 % Copyright (c) 2003-2014 by University of Queensland 4 5 % 6 % Primary Business: Queensland, Australia 7 % Licensed under the Open Software License version 3.0 8 9 % 10 % Development until 2012 by Earth Systems Science Computational Center (ESSCC) 11 % Development 2012-2013 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 high-order 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 Gauss-Labatto-Legendre 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{Cross-domain 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 multi-process 86 situations, domain sub-divisions. 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 three-dimensional 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 coordinate-tuples 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 two-dimensional 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 coordinate-tuples of points within the mesh, 135 each point tagged with the respective string within \var{diracTags}. 136 \end{funcdesc}