/[escript]/trunk/doc/user/ripley.tex
ViewVC logotype

Annotation of /trunk/doc/user/ripley.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5693 - (hide annotations)
Fri Jun 26 01:13:47 2015 UTC (4 years ago) by sshaw
File MIME type: application/x-tex
File size: 8352 byte(s)
added info on multi-resolution ripley to user guide
1 sshaw 5279
2     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 jfenwick 5593 % Copyright (c) 2003-2015 by The University of Queensland
4 sshaw 5279 % 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/osl-3.0.php
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 caltinay 5295 \chapter{The \ripley Module}\label{chap:ripley}
17 sshaw 5279 %\declaremodule{extension}{ripley}
18     %\modulesynopsis{Solving linear, steady partial differential equations using finite elements}
19    
20 jfenwick 5658 esys.ripley is an alternative domain library to esys.finley/dudley; it supports structured, uniform meshes with rectangular elements in 2D and hexahedral elements in 3D.
21 caltinay 5301 Uniform meshes allow a straightforward division of elements among processes
22     with \MPI and allow for a number of optimizations when solving PDEs.
23     \ripley also supports fast assemblers for certain types of PDE (specifically
24     Lam\'e and Wave PDEs).
25     These assemblers make use of the regular nature of the domain to optimize the
26     stiffness matrix assembly process for these specific problems.
27     Finally, \ripley is currently the only domain family that supports GPU-based
28     solvers.
29 sshaw 5279
30 caltinay 5301 As a result, \ripley domains cannot be created by reading from a mesh file
31     since only one element type is supported and all elements need to be equally
32     sized.
33     For the same reasons, \ripley does not allow assigning coordinates via
34     \function{setX}.
35     Other than that \ripley and \finley are generally interchangeable in a script
36     with both modules having the \class{Rectangle} or \class{Brick} functions
37     available. Consider the following example which creates a 2D \ripley domain:
38 sshaw 5279
39     \begin{python}
40     from esys.ripley import Rectangle, Brick
41 caltinay 5301 dom = Rectangle(9, 9)
42 sshaw 5279 \end{python}
43    
44 sshaw 5693 Multi-resolution domains are supported in \ripley via use of \class{MultiBrick}
45     and \class{MultiRectangle}. Each level of one of
46     these domains has twice the elements in each axis of the next lower resolution.
47     The \class{MultiBrick} is not currently supported when running \escript with
48     multiple processes using \MPI. Interpolation between these multi-resolution
49     domains is possible providing they have matching dimensions and subdivisions,
50     along with a compatible number of elements. To simplify these conditions the
51     use of \class{MultiResolutionDomain} is highly recommended. The following
52     example creates two 2D domains of different resolutions and interpolates
53     between them:
54    
55     \begin{python}
56     from esys.ripley import MultiResolutionDomain
57     mrd = MultiResolutionDomain(2, n0=10, n1=10)
58     ten_by_ten = mrd.getLevel(0)
59     data10 = Vector(..., Function(ten_by_ten))
60     ...
61     forty_by_forty = mrd.getLevel(2)
62     data40 = interpolate(data10, Function(forty_by_forty))
63     \end{python}
64    
65 sshaw 5279 \section{Formulation}
66     For a single PDE that has a solution with a single component the linear PDE is
67     defined in the following form:
68 caltinay 5301 \begin{equation}\label{eq:ripleysingle}
69 sshaw 5279 \begin{array}{cl} &
70     \displaystyle{
71     \int_{\Omega}
72     A_{jl} \cdot v_{,j}u_{,l}+ B_{j} \cdot v_{,j} u+ C_{l} \cdot v u_{,l}+D \cdot vu \; d\Omega }
73     + \displaystyle{\int_{\Gamma} d \cdot vu \; d{\Gamma} }\\
74     = & \displaystyle{\int_{\Omega} X_{j} \cdot v_{,j}+ Y \cdot v \; d\Omega }
75     + \displaystyle{\int_{\Gamma} y \cdot v \; d{\Gamma}}
76     \end{array}
77     \end{equation}
78    
79     \section{Meshes}
80 caltinay 5301 \label{sec:ripleymeshes}
81     An example 2D mesh from \ripley is shown in Figure~\ref{fig:ripleyrect}.
82     Mesh files cannot be used to generate \ripley domains, i.e. \ripley does not
83     have \function{ReadGmsh} or \function{ReadMesh} functions.
84     Instead, \ripley domains are always created using a call to \function{Brick}
85     or \function{Rectangle}, see Section~\ref{sec:ripleyfuncs}.
86 sshaw 5279
87     \begin{figure}
88 caltinay 5301 \centerline{\includegraphics{RipleyMesh}}
89     \caption{10x10 \ripley Rectangle created with \var{l0=(5.5, 15.5)} and
90     \var{l1=(9.0, 14.0)}}
91     \label{fig:ripleyrect}
92 sshaw 5279 \end{figure}
93    
94 caltinay 5301 \section{Functions}\label{sec:ripleyfuncs}
95 sshaw 5279 \begin{funcdesc}{Brick}{n0,n1,n2,l0=1.,l1=1.,l2=1.,d0=-1,d1=-1,d2=-1,
96     diracPoints=list(), diracTags=list()}
97     generates a \Domain object representing a three-dimensional brick between
98     $(0,0,0)$ and $(l0,l1,l2)$ with orthogonal faces. All elements will be regular.
99     The brick is filled with
100     \var{n0} elements along the $x_0$-axis,
101     \var{n1} elements along the $x_1$-axis and
102     \var{n2} elements along the $x_2$-axis.
103     If built with \MPI support, the domain will be subdivided
104     \var{d0} times along the $x_0$-axis,
105     \var{d1} times along the $x_1$-axis, and
106     \var{d2} times along the $x_2$-axis.
107     \var{d0}, \var{d1}, and \var{d2} must be factors of the number of
108     \MPI processes requested.
109     If axial subdivisions are not specified, automatic domain subdivision will take
110     place. This may not be the most efficient construction and will likely result in
111     extra elements being added to ensure proper distribution of work. Any extra
112     elements added in this way will change the length of the domain proportionately.
113     \var{diracPoints} is a list of coordinate-tuples of points within the mesh,
114     each point tagged with the respective string within \var{diracTags}.
115     \end{funcdesc}
116    
117 caltinay 5301 \begin{funcdesc}{Rectangle}{n0,n1,l0=1.,l1=1.,d0=-1,d1=-1,
118 sshaw 5279 diracPoints=list(), diracTags=list()}
119     generates a \Domain object representing a two-dimensional rectangle between
120     $(0,0)$ and $(l0,l1)$ with orthogonal faces. All elements will be regular.
121     The rectangle is filled with
122     \var{n0} elements along the $x_0$-axis and
123     \var{n1} elements along the $x_1$-axis.
124     If built with \MPI support, the domain will be subdivided
125     \var{d0} times along the $x_0$-axis and
126     \var{d1} times along the $x_1$-axis.
127     \var{d0} and \var{d1} must be factors of the number of \MPI processes requested.
128     If axial subdivisions are not specified, automatic domain subdivision will take
129     place. This may not be the most efficient construction and will likely result in
130     extra elements being added to ensure proper distribution of work. Any extra
131     elements added in this way will change the length of the domain proportionately.
132     \var{diracPoints} is a list of coordinate-tuples of points within the mesh,
133     each point tagged with the respective string within \var{diracTags}.
134     \end{funcdesc}
135    
136 caltinay 5301 \noindent The arguments \var{l0}, \var{l1} and \var{l2} for \function{Brick}
137     and \function{Rectangle} may also be given as tuples \var{(x0,x1)} in which
138     case the coordinates will range between \var{x0} and \var{x1}. For example:
139     \begin{python}
140     from esys.ripley import Rectangle
141     dom = Rectangle(10, 10, l0=(5.5, 15.5), l1=(9.0, 14.0))
142     \end{python}
143    
144     \noindent This will create a rectangle with $10$ by $10$ elements where the
145     bottom-left node is located at $(5.5, 9.0)$ and the top-right node has
146     coordinates $(15.5, 14.0)$, see Figure~\ref{fig:ripleyrect}.
147    
148 sshaw 5693 The \class{MultiResolutionDomain} class is available as a wrapper, taking the
149     dimension of the domain followed by the same arguments as \class{Brick} (if
150     a two-dimensional domain is requested, any extra arguments over those used by
151     \class{Rectangle} are ignored). All of these standard arguments to
152     \class{MultiResolutionDomain} must be supplied as keyword arguments
153     (e.g. \var{d0}=...). The \class{MultiResolutionDomain} can then generate
154     compatible domains for interpolation.
155    
156 sshaw 5279 \section{Linear Solvers in \SolverOptions}
157 caltinay 5301 Currently direct solvers and GPU-based solvers are not supported under \MPI
158     when running with more than one rank.
159 sshaw 5279 By default, \ripley uses the iterative solvers \PCG for symmetric and \BiCGStab
160     for non-symmetric problems.
161 caltinay 5301 A GPU will not be used unless explicitly requested via the
162     \function{setSolverTarget} method of the solver options.
163     These solvers are only available if \ripley was built with \CUDA support.
164 sshaw 5279 If the direct solver is selected, which can be useful when solving very
165     ill-posed equations, \ripley uses the \MKL\footnote{If the stiffness matrix is
166     non-regular \MKL may return without a proper error code. If you observe
167     suspicious solutions when using \MKL, this may be caused by a non-invertible
168     operator.} solver package. If \MKL is not available \UMFPACK is used.
169 sshaw 5693 If \UMFPACK is not available a suitable iterative solver from \PASO is used, but
170     if a direct solver was requested via the \SolverOptions an exception will be
171     raised.
172 sshaw 5279
173    
174    

  ViewVC Help
Powered by ViewVC 1.1.26