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

Contents of /trunk/doc/user/faultsystem.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3989 - (show annotations)
Tue Sep 25 02:21:54 2012 UTC (6 years, 10 months ago) by jfenwick
File MIME type: application/x-tex
File size: 15462 byte(s)
More copyright fixes.
pyvisi traces removed.
Some install doco
1
2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 % Copyright (c) 2003-2012 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/osl-3.0.php
9 %
10 % Development until 2012 by Earth Systems Science Computational Center (ESSCC)
11 % Development since 2012 by School of Earth Sciences
12 %
13 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14
15 \section{Fault System}
16 \label{Fault System}
17 The \class{FaultSystem} class provides an easy-to-use interface to handle 2D
18 and 3D fault systems\index{faults} as used for instance in simulating fault
19 ruptures. The main purpose of the class is to provide a parameterization of
20 an individual fault in the system of faults.
21 In case of a 2D fault the fault is parameterized by a single value $w_{0}$ and
22 in the case of a 3D fault two parameters $w_{0}$ and $w_{1}$ are used.
23 This parameterization can be used to impose data (e.g. a slip distribution)
24 onto the fault. It can also be a useful tool to visualize or analyze the
25 results on the fault if the fault is not straight.
26
27 \begin{figure}
28 \centering
29 \includegraphics{FaultSystem2D}
30 \caption{\label{FAULTSYSTEM2D}Two dimensional fault system with one fault
31 named `t` in the $(x_{0},x_{1})$ space and its parameterization in the
32 $w_{0}$ space. The fault has three segments.}
33 \end{figure}
34
35 A fault $t$ in the fault system is represented by a starting point $V^{t0}$
36 and series of directions, called strikes\index{strike}, and the lengths $(l^{ti})$.
37 The strike of segment $i$ is defined by the angle $\sigma^{ti}$ between the
38 $x_{0}$-axis and the direction of the fault, see Figure~\ref{FAULTSYSTEM2D}.
39 The length and strike defines the polyline $(V^{ti})$ of the fault by
40 \begin{equation}
41 V^{ti} = V^{t(i-1)} +
42 l^{ti} \cdot S^{ti}
43 \mbox{ with }
44 S^{ti} =
45 \left[
46 \begin{array}{c}
47 cos(\sigma^{ti}) \\
48 sin(\sigma^{ti}) \\
49 0
50 \end{array}
51 \right]
52 \label{eq:fault 00}
53 \end{equation}
54 In the 3D case each fault segment $i$ has an additional dip\index{dip}
55 $\theta^{ti}$ and at each vertex $i$ a depth $\delta^{ti}$ is given.
56 The fault segment normal $n^{ti}$ is given by
57 \begin{equation}
58 n^{ti} =
59 \left[
60 \begin{array}{c}
61 -sin(\theta^{ti}) \cdot S^{ti}_{1} \\
62 sin(\theta^{ti}) \cdot S^{ti}_{0} \\
63 cos(\theta^{ti})
64 \end{array}
65 \right]
66 \label{eq:fault 0}
67 \end{equation}
68 At each vertex we define a depth vector $d^{ti}$ defined as the intersect of
69 the fault planes of segment $(i-1)$ and $i$ where for the first segment and
70 last segment the vector orthogonal to strike vector $S^{ti}$\index{strike}
71 and the segment normal $n^{ti}$ is used. The direction $\tilde{d}^{ti}$ of the
72 depth vector is given as
73 \begin{equation}
74 \tilde{d}^{ti} = n^{ti} \times n^{t(i-1)}
75 \label{eq:fault b}
76 \end{equation}
77 If $\tilde{d}^{ti}$ is zero the strike vectors $L^{t(i-1)}$ and $L^{ti}$ are
78 collinear and we can set $\tilde{d}^{ti} = l^{ti} \times n^{ti}$.
79 If the two fault segments are almost orthogonal $\tilde{d}^{ti}$ is pointing
80 in the direction of $L^{t(i-1)}$ and $L^{ti}$. In this case no depth can be
81 defined. So we will reject a fault system if
82 \begin{equation}
83 min(\| \tilde{d}^{ti} \times L^{t(i-1)} \|,\| \tilde{d}^{ti} \times L^{ti} \|)
84 \le 0.1 \cdot \| \tilde{d}^{ti} |
85 \label{eq:fault c}
86 \end{equation}
87 which corresponds to an angle of less than $10^o$ between the depth vector and
88 the strike. We then set
89 \begin{equation}
90 d^{ti}=\delta^{ti} \cdot \frac{\tilde{d}^{ti}}{\|\tilde{d}^{ti}\|}
91 \label{eq:fault d}
92 \end{equation}
93 We can then define the polyline $(v^{ti})$ for the bottom of the fault as
94 \begin{equation}
95 v^{ti}= V^{ti}+d^{ti}
96 \label{eq:fault e}
97 \end{equation}
98 In order to simplify working on a fault $t$ in a fault system a
99 parameterization $P^t: (w_{0},w_{1}) \rightarrow (x_{0},x_{1},x_{2})$ over a
100 rectangular domain is introduced such that
101 \begin{equation}
102 0\le w_{0} \le w^t_{0 max} \mbox{ and } -w^t_{1max}\le w_{1} \le 0
103 \label{eq:fault 1}
104 \end{equation}
105 with positive numbers $w^t_{0 max}$ and $w^t_{1 max}$. Typically one chooses
106 $w^t_{0 max}$ to be the unrolled length of the fault and $w^t_{1 max}$ to be
107 the mean value of segment depth. Moreover we have
108 \begin{equation}
109 P^t(W^{ti})=V^{ti}\mbox{ and } P^t(w^{ti})=v^{ti}\
110 \label{eq:fault 2}
111 \end{equation}
112 where
113 \begin{equation}
114 W^{ti}=(\Omega^{ti},0) \mbox{ and } w^{ti}=(\Omega^{ti},-w^t_{1 max})
115 \label{eq:fault 3}
116 \end{equation}
117 and $\Omega^{ti}$ is the unrolled distance of $W^{ti}$ from $W^{t0}$, i.e.
118 $l^{ti}=\Omega^{t(i+1)}-\Omega^{ti}$. In the 2D case $w^t_{1 max}$ is set to
119 zero and therefore the second component is dropped, see Figure~\ref{FAULTSYSTEM2D}.
120
121 In the 2D case the parameterization $P^t$ is constructed as follows:
122 The line connecting $V^{t(i-1)}$ and $V^{ti}$ is given by
123 \begin{equation}
124 x=V^{ti} + s \cdot ( V^{t(i+1)}- V^{ti} )
125 \label{eq:2D line 1}
126 \end{equation}
127 where $s$ is between $0$ and $1$. The point $x$ is on $i$-th fault segment if
128 and only if such an $s$ exists. Assuming $x$ is on the fault it can be
129 calculated as
130 \begin{equation}
131 s = \frac{ (x- V^{ti})^t \cdot (V^{t(i+1)}- V^{ti}) }{ \|V^{t(i+1)}- V^{ti}\|^2}
132 \label{eq:2D line 1b}
133 \end{equation}
134 We then can set
135 \begin{equation}
136 w_{0}=\Omega^{ti}+s \cdot (\Omega^{ti}-\Omega^{t(i-1)})
137 \label{eq:2D line 2}
138 \end{equation}
139 to get $P^t(w_{0})=x$.
140 It remains the question if the given $x$ is actually on the segment $i$ of
141 fault $t$. To test this $s$ is restricted between $0$ and $1$ (so if $s<0$, $s$
142 is set to $0$ and if $s>1$, $s$ is set to $1$) and then we check the residual
143 of \eqn{eq:2D line 1}, i.e. $x$ has been accepted to be in the segment if
144 \begin{equation}
145 \|x-V^{ti} - s \cdot (V^{t(i+1)}- V^{ti}) \| \le tol \cdot
146 max(l^{ti}, \|x-V^{ti} \|)
147 \label{eq:2D line 3}
148 \end{equation}
149 where $tol$ is a given tolerance.
150
151 In the 3D case the situation is a bit more complicated: we split the fault
152 segment across the diagonal $V^{ti}$-$v^{t(i+1)}$ to produce two triangles.
153 In the upper triangle we use the parameterization
154 \begin{equation}
155 x= V^{ti} + s \cdot (V^{t(i+1)}-V^{ti}) + r \cdot (v^{t(i+1)}-V^{t(i+1)})
156 \mbox{ with } r \le s;
157 \label{eq:2D line 4}
158 \end{equation}
159 while in the lower triangle we use
160 \begin{equation}
161 x= V^{ti} + s \cdot (v^{t(i+1)}-v^{ti}) + r \cdot (v^{ti}-V^{ti})
162 \mbox{ with } s \le r;
163 \label{eq:2D line 4b}
164 \end{equation}
165 where $0\le s,r \le 1$. Both equations are solved in the least-squares sense
166 e.g. using the Moore–Penrose pseudo-inverse for the coefficient matrices.
167 The resulting $s$ and $r$ are then restricted to the unit square. Similar to
168 the 2D case (see \eqn{eq:2D line 3}) we identify $x$ to be in the upper
169 triangle of the segment if
170 \begin{equation}
171 \|x- V^{ti} - s \cdot (V^{t(i+1)}-V^{ti}) - r \cdot (v^{t(i+1)}-V^{t(i+1)}) \|
172 \le tol \cdot max(\|x-V^{ti} \|,\|v^{t(i+1)}-V^{t(i)})\|)
173 \label{eq:2D line 4c}
174 \end{equation}
175 and in the lower part
176 \begin{equation}
177 \|x-V^{ti} - s \cdot (v^{t(i+1)}-v^{ti}) - r \cdot (v^{ti}-V^{ti}) \|
178 \le tol \cdot max(\|x-V^{ti} \|,\|v^{t(i+1)}-V^{t(i)})\|)
179 \label{eq:2D line 4d}
180 \end{equation}
181 after the restriction of $(s,t)$ to the unit square.
182 Note that $\|v^{t(i+1)}-V^{t(i)})\|$ is the length of the diagonal of the
183 fault segment. For those $x$ which have been located in the $i$-th segment we
184 then set
185 \begin{equation}
186 w_{0}=\Omega^{ti}+s \cdot (\Omega^{ti}-\Omega^{t(i-1)})
187 \mbox{ and }
188 w_{1}=w^t_{1max} (r-1)
189 \label{eq:2D line 5}
190 \end{equation}
191
192 \subsection{Functions}
193
194 \begin{classdesc}{FaultSystem}{\optional{dim =3}}
195 creates a fault system in the \var{dim} dimensional space.
196 \end{classdesc}
197
198 \begin{methoddesc}[FaultSystem]{getMediumDepth}{tag}
199 returns the medium depth of fault \var{tag}.
200 \end{methoddesc}
201
202 \begin{methoddesc}[FaultSystem]{getTags}{}
203 returns a list of the tags used by the fault system.
204 \end{methoddesc}
205
206 \begin{methoddesc}[FaultSystem]{getStart}{tag}
207 returns the starting point of fault \var{tag} as a \numpyNDA object.
208 \end{methoddesc}
209
210 \begin{methoddesc}[FaultSystem]{getDim}{}
211 returns the spatial dimension.
212 \end{methoddesc}
213
214 \begin{methoddesc}[FaultSystem]{getDepths}{tag}
215 returns the list of the depths of the segments in fault \var{tag}.
216 \end{methoddesc}
217
218 \begin{methoddesc}[FaultSystem]{getTopPolyline}{tag}
219 returns the polyline used to describe the fault tagged by \var{tag}.
220 \end{methoddesc}
221
222 \begin{methoddesc}[FaultSystem]{getStrikes}{tag}
223 returns the list of strikes $\sigma^{ti}$ of the segments in fault
224 $t=$\var{tag}.
225 \end{methoddesc}
226
227 \begin{methoddesc}[FaultSystem]{getStrikeVectors}{tag}
228 returns the strike vectors $S^{ti}$ of fault $t=$\var{tag}.
229 \end{methoddesc}
230
231 \begin{methoddesc}[FaultSystem]{getLengths}{tag}
232 returns the lengths $l^{ti}$ of the segments in fault $t=$\var{tag}.
233 \end{methoddesc}
234
235 \begin{methoddesc}[FaultSystem]{getTotalLength}{tag}
236 returns the total unrolled length of fault \var{tag}.
237 \end{methoddesc}
238
239 \begin{methoddesc}[FaultSystem]{getDips}{tag}
240 returns the list of the dips of the segments in fault \var{tag}.
241 \end{methoddesc}
242
243 \begin{methoddesc}[FaultSystem]{getBottomPolyline}{tag}
244 returns the list of the vertices defining the bottom of the fault \var{tag}.
245 \end{methoddesc}
246
247 \begin{methoddesc}[FaultSystem]{getSegmentNormals}{tag}
248 returns the list of the normals of the segments in fault \var{tag}.
249 \end{methoddesc}
250
251 \begin{methoddesc}[FaultSystem]{getDepthVectors}{tag}
252 returns the list of the depth vectors $d^{ti}$ for fault $t=$\var{tag}.
253 \end{methoddesc}
254
255 \begin{methoddesc}[FaultSystem]{getDepths}{tag}
256 returns the list of the depths of the segments in fault \var{tag}.
257 \end{methoddesc}
258
259 \begin{methoddesc}[FaultSystem]{getW0Range}{tag}
260 returns the range of the parameterization in $w_{0}$.
261 For tag $t$ this is the pair $(\Omega^{t0},\Omega^{tn})$ where $n$ is the
262 number of segments in the fault.
263 In most cases one has $(\Omega^{t0},\Omega^{tn})=(0,w^t_{0 max})$.
264 \end{methoddesc}
265
266 \begin{methoddesc}[FaultSystem]{getW1Range}{tag}
267 returns the range of the parameterization in $w_{1}$.
268 For tag $t$ this is the pair $(-w^t_{1max},0)$.
269 \end{methoddesc}
270
271 \begin{methoddesc}[FaultSystem]{getW0Offsets}{tag}
272 returns the offsets for the parameterization of fault \var{tag}.
273 For tag \var{tag}=$t$ this is the list $[\Omega^{ti}]$.
274 \end{methoddesc}
275
276 \begin{methoddesc}[FaultSystem]{getCenterOnSurface}{}
277 returns the center point of the fault system at the surfaces.
278 In 3D the calculation of the center is considering the top edge of the faults
279 and projects the edge to the surface (the $x_{2}$ component is assumed to be
280 0). An \numpyNDA object is returned.
281 \end{methoddesc}
282
283 \begin{methoddesc}[FaultSystem]{getOrientationOnSurface}{}
284 returns the orientation of the fault system in RAD on the surface
285 ($x_{2}=0$ plane) around the fault system center.
286 \end{methoddesc}
287
288 \begin{methoddesc}[FaultSystem]{transform}{\optional{rot=0, \optional{shift=numpy.zeros((3,)}}}
289 applies a shift \var{shift} and a consecutive rotation in the $x_{2}=0$ plane.
290 \var{rot} is a float number and \var{shift} an \numpyNDA object.
291 \end{methoddesc}
292
293 \begin{methoddesc}[FaultSystem]{getMaxValue}{f\optional{, tol=1.e-8}}
294 returns the tag of the fault where \var{f} takes the maximum value and a
295 \class{Locator} object which can be used to collect values from \Data objects
296 at the location where the maximum is taken, e.g.
297 \begin{python}
298 fs=FaultSystem()
299 f=Scalar(..)
300 t, loc=fs.getMaxValue(f)
301 print("maximum value of f on the fault %s is %s at location %s."%(t, \
302 loc(f), loc.getX()))
303 \end{python}
304 \var{f} must be a \Scalar. When the maximum is calculated only
305 \DataSamplePoints are considered which are on a fault in the fault system in
306 the sense of condition~\ref{eq:2D line 3} or \ref{eq:2D line 4d}, respectively.
307 In the case no \DataSamplePoints are found the returned tag is \var{None} and
308 the maximum value as well as the location of the maximum value are undefined.
309 \end{methoddesc}
310
311 \begin{methoddesc}[FaultSystem]{getMinValue}{f\optional{, tol=1.e-8}}
312 returns the tag of the fault where \var{f} takes the minimum value and a
313 \class{Locator} object which can be used to collect values from \Data objects
314 at the location where the minimum is taken, e.g.
315 \begin{python}
316 fs=FaultSystem()
317 f=Scalar(..)
318 t, loc=fs.getMinValue(f)
319 print "minimum value of f on the fault %s is %s at location."%(t,loc(f),loc.getX())
320 \end{python}
321 \var{f} must be a \Scalar. When the minimum is calculated only
322 \DataSamplePoints are considered which are on a fault in the fault system in
323 the sense of condition~\ref{eq:2D line 3} or \ref{eq:2D line 4d}, respectively.
324 In the case no \DataSamplePoints are found the returned tag is \var{None} and
325 the minimum value as well as the location of the minimum value are undefined.
326 \end{methoddesc}
327
328 \begin{methoddesc}[FaultSystem]{getParametrization}{x,tag \optional{\optional{, tol=1.e-8}, outsider=None}}
329 returns the argument $w$ of the parameterization $P^t$ for \var{tag}=$t$ to
330 provide \var{x} together with a mask indicating where the given location if on
331 a fault in the fault system by the value $1$ (otherwise the value is set to $0$).
332 \var{x} needs to be a \Vector or \numpyNDA object.
333 \var{tol} defines the tolerance to decide if given \DataSamplePoints are on
334 fault \var{tag}. The value \var{outside} is the value used as a replacement
335 value for $w$ where the corresponding value in \var{x} is not on a fault.
336 If \var{outside} is not present an appropriate value is used.
337 \end{methoddesc}
338
339 \begin{methoddesc}[FaultSystem]{getSideAndDistance}{x,tag}
340 returns the side and the distance at locations \var{x} from the fault \var{tag}.
341 \var{x} needs to be a \Vector or \numpyNDA object.
342 Positive values for side means that the corresponding location is to the right
343 of the fault, a negative value means that the corresponding location is
344 to the left of the fault. The value zero means that the side is undefined.
345 \end{methoddesc}
346
347 \begin{methoddesc}[FaultSystem]{getFaultSegments}{tag}
348 returns the polylines used to describe fault \var{tag}. For \var{tag}=$t$ this
349 is the list of the vertices $[V^{ti}]$ for the 2D and the pair of lists of the
350 top vertices $[V^{ti}]$ and the bottom vertices $[v^{ti}]$ in 3D.
351 Note that the coordinates are represented as \numpyNDA objects.
352 \end{methoddesc}
353
354 \begin{methoddesc}[FaultSystem]{addFault}{
355 strikes\optional{,
356 ls\optional{,
357 V0=[0.,0.,0.]\optional{,
358 tag=None\optional{,
359 dips=None\optional{,
360 depths= None\optional{,
361 w0_offsets=None\optional{,
362 w1_max=None}}}}}}}}
363 adds the fault \var{tag} to the fault system.
364 \var{V0} defines the start point of fault named $t=$\var{tag}.
365 The polyline defining the fault segments on the surface are set by the strike
366 angles \var{strikes} (=$\sigma^{ti}$, north = $\pi/2$, the orientation is
367 counterclockwise.) and the length \var{ls} (=$l^{ti}$).
368 In the 3D case one also needs to define the dip angles \var{dips}
369 (=$\delta^{ti}$, vertical=$0$, right-hand rule applies.) and the depth
370 \var{depths} for each segment.
371 \var{w1_max} defines the range of $w_{1}$.
372 If not present the mean value over the depth of all segment edges in the fault
373 is used.
374 \var{w0_offsets} sets the offsets $\Omega^{ti}$. If not present it is chosen
375 such that $\Omega^{ti}-\Omega^{t(i-1)}$ is the length of the $i$-th segment.
376 In some cases, e.g. when kinks in the fault are relevant, it can be useful
377 to explicitly specify the offsets in order to simplify the assignment of values.
378 \end{methoddesc}
379
380 \subsection{Example}
381 See \Sec{Slip CHAP}.
382

  ViewVC Help
Powered by ViewVC 1.1.26