# Diff of /trunk/doc/user/faultsystem.tex

revision 2662 by jfenwick, Wed Sep 9 23:47:10 2009 UTC revision 2663 by gross, Tue Sep 15 06:04:44 2009 UTC
# Line 9  $w\hackscore{0}$ space. The fault has th Line 9  $w\hackscore{0}$ space. The fault has th
9  The \class{FaultSystem} is an easy to use interface to handle 2D and 3D fault systems \index{faults} as used for instance in simulating fault ruptures. The main purpose of the class is to provide a parameterization of an individual fault in the system of fault. In case of a 2D fault the fault is parameterized by a single value $w\hackscore{0}$ and in the case of a 3D fault two parameters $w\hackscore{0}$ and $w\hackscore{1}$ are used. This parameterization can be used  The \class{FaultSystem} is an easy to use interface to handle 2D and 3D fault systems \index{faults} as used for instance in simulating fault ruptures. The main purpose of the class is to provide a parameterization of an individual fault in the system of fault. In case of a 2D fault the fault is parameterized by a single value $w\hackscore{0}$ and in the case of a 3D fault two parameters $w\hackscore{0}$ and $w\hackscore{1}$ are used. This parameterization can be used
10  to impose data (e.g. a slip distribution) onto the fault. It can also be a useful tool to visualize or analyze the results on the fault if the fault is not straight.  to impose data (e.g. a slip distribution) onto the fault. It can also be a useful tool to visualize or analyze the results on the fault if the fault is not straight.
11
12  A fault $t$ in the fault system is represented by two polygons $(V^{ti})$ and $(v^{ti})$  A fault $t$ in the fault system is represented by a staring point $V^{t0}$ and series of
13  defining the top and bottom line of the fault $t$.  direction, called strikes~\index{strike}, and the lengths $(l^{ti})$.
14  $V^{ti}$ defines the $i$-th fault vertex at the top of the fault (typically at the surface of the Earth) and  The strike of segment $i$ is defined by the angle $\sigma^{ti}$ between the $x\hackscore{0}$-axis and the
15  $v^{ti}$ defines the $i$-th fault vertex at the bottom of the fault. Both polygons need to contain the same number of  direction of the fault, see Figure~\ref{FAULTSYSTEM2D}. The length and strike defines the
16  vertices. For the 2D case the polygon $(v^{ti})$ for the bottom edge of the fault is dropped.  polyline $(V^{ti})$ of the fault by
17  The patch with the vertices
18  $V^{t(i-1)}$, $V^{ti}$  V^{ti} = V^{t(i-1)} +
19  $v^{t(i-1)}$, and $v^{ti}$  l^{ti} \cdot  S^{ti}
20  is called the $i$-th segment of the fault t. In 2D the the line with the start point $V^{t(i-1)}$  \mbox{ with }
21  and the end point $V^{ti}$ is called the $i$-th segment, see Figure~\ref{FAULTSYSTEM2D}.  S^{ti} =
22    \left[
23  In general a fault does not define a plane surface (or a straight line in 2D). In order to simplify working on  \begin{array}{c}
24  a fault in a fault system a parameterization $P^t: (w\hackscore{0},w\hackscore{1}) \rightarrow (x\hackscore{0},x\hackscore{1},x\hackscore{2})$ over a rectangular domain is introduced such that   cos(\sigma^{ti})  \\
25     sin(\sigma^{ti}) \\
26     0
27    \end{array}
28    \right]
29    \label{eq:fault 00}
30
31    In the 3D case each fault segment $i$ has an additional dip \index{dip} $\theta^{ti}$ and
32    and at each vertex $i$ a depth $\delta^{ti}$ is given. The fault segment normal $n^{ti}$ is given by
33
34    n^{ti} =
35    \left[
36    \begin{array}{c}
37     -sin(\theta^{ti}) \cdot S^{ti}\hackscore{1} \\
38     sin(\theta^{ti}) \cdot S^{ti}\hackscore{0} \\
39     cos(\theta^{ti})
40    \end{array}
41    \right]
42    \label{eq:fault 0}
43
44    At each vertex we define a depth vector $d^{ti}$ defined as the
45    intersect of the fault planes of segment $(i-1)$ and $i$ where
46    for the first segment and last segment the vector orthogonal to strike vector $S^{ti}$\index{strike}
47    and the segment normal $n^{ti}$ is used. The direction $\tilde{d}^{ti}$ of the depth vector is
48    given as
49
50    \tilde{d}^{ti} = n^{ti} \times n^{t(i-1)}
51    \label{eq:fault b}
52
53    If $\tilde{d}^{ti}$ is zero the strike vectors $L^{t(i-1)}$ and $L^{ti}$ are collinear and
54    we can set $\tilde{d}^{ti} = l^{ti} \times n^{ti}$. If the two fault segments are almost
55    orthogonal $\tilde{d}^{ti}$ is pointing in the direction of $L^{t(i-1)}$ and $L^{ti}$. In this case no
56    depth can be defined. So we will reject a fault system if
57
58    min(\| \tilde{d}^{ti}  \times  L^{t(i-1)} \|,\| \tilde{d}^{ti}  \times  L^{ti} \|)
59    \le 0.1 \cdot \| \tilde{d}^{ti} |
60    \label{eq:fault c}
61
62    which corresponds to an angle of less then $10^o$ between the depth vector and the strike. We then set
63
64    d^{ti}=\delta^{ti} \cdot \frac{\tilde{d}^{ti}}{\|\tilde{d}^{ti}\|}
65    \label{eq:fault d}
66
67    We can then define the polyline $(v^{ti})$ for the bottom of the fault as
68
69    v^{ti}= V^{ti}+d^{ti}
70    \label{eq:fault e}
71
72    In order to simplify working on
73    a fault $t$ in a fault system a parameterization $P^t: (w\hackscore{0},w\hackscore{1}) \rightarrow (x\hackscore{0},x\hackscore{1},x\hackscore{2})$ over a rectangular domain is introduced such that
74
75  0\le w\hackscore{0} \le w^t\hackscore{0 max} \mbox{ and }  -w^t\hackscore{1max}\le w\hackscore{1} \le 0  0\le w\hackscore{0} \le w^t\hackscore{0 max} \mbox{ and }  -w^t\hackscore{1max}\le w\hackscore{1} \le 0
76  \label{eq:fault 1}  \label{eq:fault 1}
# Line 35  P^t(W^{ti})=V^{ti}\mbox{ and } P^t(w^{ti Line 84  P^t(W^{ti})=V^{ti}\mbox{ and } P^t(w^{ti
84
85  where  where
86
87  W^{ti}=(d^{ti},0) \mbox{ and } w^{ti}=(d^{ti},-w^t\hackscore{1 max})  W^{ti}=(\Omega^{ti},0) \mbox{ and } w^{ti}=(\Omega^{ti},-w^t\hackscore{1 max})
88  \label{eq:fault 3}  \label{eq:fault 3}
89
90  and $d^{ti}$ is the unrolled distance of $W^{ti}$ from $W^{t0}$. In the 2D case $w^t\hackscore{1 max}$ is set to zero and therefore the second component is dropped, see Figure~\ref{FAULTSYSTEM2D}.  and $\Omega^{ti}$ is the unrolled distance of $W^{ti}$ from $W^{t0}$, ie $l^{ti}=\Omega^{t(i+1)}-\Omega^{ti}$. In the 2D case $w^t\hackscore{1 max}$ is set to zero and therefore the second component is dropped, see Figure~\ref{FAULTSYSTEM2D}.
91
92  In the case of 2D the parameterization $P^t$ is constructed as follows:  In the case of 2D the parameterization $P^t$ is constructed as follows:
93  The line connecting $V^{t(i-1)}$ and $V^{ti}$ is given by  The line connecting $V^{t(i-1)}$ and $V^{ti}$ is given by
94
95  x=V^{t(i-1)} + s \cdot (V^{ti}-V^{t(i-1)})  x=V^{ti} + s  \cdot  ( V^{t(i+1)}- V^{ti} )
96  \label{eq:2D line 1}  \label{eq:2D line 1}
97
98  where $s$ is between $0$ and $1$. The point $x$ is on $i$-th fault segment if and only if  where $s$ is between $0$ and $1$. The point $x$ is on $i$-th fault segment if and only if
99  such an $s$ exists. If assume $x$ is on the fault one can calculate $s$ as  such an $s$ exists. If assume $x$ is on the fault one can calculate $s$ as
100
101  s = \frac{ (x- V^{t(i-1)})^t \cdot (V^{ti}-V^{t(i-1)}) }{\|V^{ti}-V^{t(i-1)}\|^2}  s = \frac{ (x- V^{ti})^t \cdot (V^{t(i+1)}- V^{ti}) }{ \|V^{t(i+1)}- V^{ti}\|^2}
102  \label{eq:2D line 1b}  \label{eq:2D line 1b}
103
104  We then can set  We then can set
105
106  w\hackscore{0}=d^{ti}+s \cdot (d^{ti}-d^{t(i-1)})  w\hackscore{0}=\Omega^{ti}+s \cdot (\Omega^{ti}-\Omega^{t(i-1)})
107  \label{eq:2D line 2}  \label{eq:2D line 2}
108
109  to get $P^t(w\hackscore{0})=x$.  to get $P^t(w\hackscore{0})=x$.
# Line 62  It remains the question if the given $x$ Line 111  It remains the question if the given $x$
111  between $0$ and $1$ (so if $s<0$ $s$ is set to $0$ and if $s>1$ $s$ is set to $1$) and the we check the  between $0$ and $1$ (so if $s<0$ $s$ is set to $0$ and if $s>1$ $s$ is set to $1$) and the we check the
112  residual of equation~\ref{eq:2D line 1}, ie. $x$ is been accepted to be in the segment if  residual of equation~\ref{eq:2D line 1}, ie. $x$ is been accepted to be in the segment if
113
114  \|x-V^{t(i-1)} - s \cdot (V^{ti}-V^{t(i-1)}) \| \le tol \cdot max(\|V^{ti}-V^{t(i-1)}\|, \|x-V^{t(i-1)} \|)  \|x-V^{ti} - s \cdot (V^{t(i+1)}- V^{ti}) \| \le tol \cdot
115    max(l^{ti}, \|x-V^{ti} \|)
116  \label{eq:2D line 3}  \label{eq:2D line 3}
117
118  where $tol$ is a given tolerance.  where $tol$ is a given tolerance.
119
120  ADD DISCRIPTION FOR 3D case.  In the 3D case the situation is a bit more complicated: we split the fault segment across
121    the diagonal $V^{ti}$-$v^{t(i+1)}$ to produce two triangles. In the upper triangle we use the
122    parameterization
123
124    x= V^{ti} + s \cdot (V^{t(i+1)}-V^{ti})  + r \cdot (v^{t(i+1)}-V^{t(i+1)})
125    \mbox{ with } r \le s;
126    \label{eq:2D line 4}
127
128    while in the lower triangle we use
129
130    x= V^{ti} +  s \cdot (v^{t(i+1)}-v^{ti}) + r \cdot (v^{ti}-V^{ti})
131    \mbox{ with } s \le r;
132    \label{eq:2D line 4b}
133
134    where $0\le s,r \le 1$. Both equations are solved in the least-squares sense e.g. using the Moore–Penrose pseudo-inverse for the coefficient matrices.  The resulting $s$ and $r$  are then restricted to the unit square. Similar to the 2D case (see equation~\ref{eq:2D line 3}) we identify $x$ to be in the upper triangle of the segment if
135
136    \|x- V^{ti} - s \cdot (V^{t(i+1)}-V^{ti})  - r \cdot (v^{t(i+1)}-V^{t(i+1)}) \|
137    \le tol \cdot  max(\|x-V^{ti} \|,\|v^{t(i+1)}-V^{t(i)})\|)
138    \label{eq:2D line 4c}
139
140    and in the lower part
141
142    \|x-V^{ti} -  s \cdot (v^{t(i+1)}-v^{ti}) - r \cdot (v^{ti}-V^{ti}) \|
143    \le tol \cdot  max(\|x-V^{ti} \|,\|v^{t(i+1)}-V^{t(i)})\|)
144    \label{eq:2D line 4d}
145
146    after the restriction of $(s,t)$ to the unit square. Note that $\|v^{t(i+1)}-V^{t(i)})\|$ is length of the
147    diagonal of the fault segment. For those $x$ which have been located in the $i$-th segment  we then set
148
149    w\hackscore{0}=\Omega^{ti}+s \cdot (\Omega^{ti}-\Omega^{t(i-1)})
150    \mbox{ and }
151    w\hackscore{1}=w^t\hackscore{1max} (r-1)
152    \label{eq:2D line 5}
153
154
155
156  \subsection{Functions}  \subsection{Functions}
157
# Line 76  ADD DISCRIPTION FOR 3D case. Line 160  ADD DISCRIPTION FOR 3D case.
160  Creates a fault system in the \var{dim} dimensional space.  Creates a fault system in the \var{dim} dimensional space.
161  \end{classdesc}  \end{classdesc}
162
163    \begin{methoddesc}[FaultSystem]{getMediumDepth}{tag}
164    returns the medium depth of fault \var{tag}.
165    \end{methoddesc}
166
167    \begin{methoddesc}[FaultSystem]{getTags}{}
168    returns a list of the tags used by the fault system
169    \end{methoddesc}
170
171    \begin{methoddesc}[FaultSystem]{getStart}{tag}
172    returns the starting point of fault \var{tag} as a \numpyNDA object.
173    \end{methoddesc}
174
175  \begin{methoddesc}[FaultSystem]{getDim}{}  \begin{methoddesc}[FaultSystem]{getDim}{}
176  returns the spatial dimension  returns the spatial dimension
177  \end{methoddesc}  \end{methoddesc}
178  \begin{methoddesc}[FaultSystem]{getLength}{tag}
179  returns the unrolled length of fault \var{tag}.  \begin{methoddesc}[FaultSystem]{getDepths}{tag}
180    returns the list of the depths of the segements in fault \var{tag}.
181  \end{methoddesc}  \end{methoddesc}
182
183  \begin{methoddesc}[FaultSystem]{getDepth}{tag}
184  returns the medium depth of fault \var{tag}.  \begin{methoddesc}[FaultSystem]{getTopPolyline}{tag}
185    returns the polyline used to describe fault tagged by \var{tag}
186  \end{methoddesc}  \end{methoddesc}
187
188  \begin{methoddesc}[FaultSystem]{getTags}{}  \begin{methoddesc}[FaultSystem]{getStrikes}{tag}
189  returns a list of the tags used by the fault system  returns the list of strikes $\sigma^{ti}$ of the segements in fault $t=$\var{tag}
190    \end{methoddesc}
191
192
193    \begin{methoddesc}[FaultSystem]{getStrikeVectors}{tag}
194    returns the strike vectors $S^{ti}$ of fault $t=$\var{tag}
195    \end{methoddesc}
196
197
198    \begin{methoddesc}[FaultSystem]{getLengths}{tag}
199    returns the lengths $l^{ti}$ of segments in fault $t=$\var{tag}
200    \end{methoddesc}
201
202
203    \begin{methoddesc}[FaultSystem]{getTotalLength}{tag}
204    returns the total unrolled length of fault \var{tag}
205    \end{methoddesc}
206
207    \begin{methoddesc}[FaultSystem]{getDips}{tag}
208    returns the list of the dips of the segements in fault \var{tag}.
209    \end{methoddesc}
210
211    \begin{methoddesc}[FaultSystem]{getBottomPolyline}{tag}
212    returns the list of the vertices defining the bottom of the fault \var{tag}.
213    \end{methoddesc}
214
215    \begin{methoddesc}[FaultSystem]{getSegmentNormals}{tag}
216    returns the list of the normals of the segments in fault \var{tag}.
217    \end{methoddesc}
218
219    \begin{methoddesc}[FaultSystem]{getDepthVectors}{tag}
220    returns the list of the depth vectors $d^{ti}$ for fault $t=$\var{tag}.
221    \end{methoddesc}
222
223    \begin{methoddesc}[FaultSystem]{getDepths}{tag}
224    returns the list of the depths of the segements in fault \var{tag}.
225  \end{methoddesc}  \end{methoddesc}
226
227  \begin{methoddesc}[FaultSystem]{getW0Range}{tag}  \begin{methoddesc}[FaultSystem]{getW0Range}{tag}
228  returns the range of the parameterization in $w\hackscore{0}$.  returns the range of the parameterization in $w\hackscore{0}$.
229  For tag $t$ this is the pair $(d^{t0},d^{tn})$ where $n$ is the number of segments in the fault.  For tag $t$ this is the pair $(\Omega^{t0},\Omega^{tn})$ where $n$ is the number of segments in the fault.
230  In most cases one has $(d^{t0},d^{tn})=(0,w^t\hackscore{0 max})$.  In most cases one has $(\Omega^{t0},\Omega^{tn})=(0,w^t\hackscore{0 max})$.
231  \end{methoddesc}  \end{methoddesc}
232
233  \begin{methoddesc}[FaultSystem]{getW1Range}{tag}  \begin{methoddesc}[FaultSystem]{getW1Range}{tag}
# Line 106  For tag $t$ this is the pair $(-w^t\hack Line 237 For tag$t$this is the pair$(-w^t\hack
237
238  \begin{methoddesc}[FaultSystem]{getW0Offsets}{tag}  \begin{methoddesc}[FaultSystem]{getW0Offsets}{tag}
239  returns the offsets for the parameterization of fault \var{tag}.  returns the offsets for the parameterization of fault \var{tag}.
240  For tag \var{tag}=$t$ this is the list $[d^{ti}]$.  For tag \var{tag}=$t$ this is the list $[\Omega^{ti}]$.
\end{methoddesc}

\begin{methoddesc}[FaultSystem]{getFaultSegments}{tag}
returns the polygons used to describe fault \var{tag}. For \var{tag}=$t$ this is the list of the vertices
$[V^{ti}]$ for the 2D and the pair of lists of the top vertices $[V^{ti}]$ and the bottom vertices  $[v^{ti}]$ in 3D.
Note that the coordinates are represented as \numpyNDA objects.
241  \end{methoddesc}  \end{methoddesc}
242
243  \begin{methoddesc}[FaultSystem]{getCenterOnSurface}{}  \begin{methoddesc}[FaultSystem]{getCenterOnSurface}{}
# Line 129  applies a shift \var{shift} and a consec Line 253  applies a shift \var{shift} and a consec
253  \var{rot} is a float number and \var{shift} an \numpyNDA object.  \var{rot} is a float number and \var{shift} an \numpyNDA object.
254  \end{methoddesc}  \end{methoddesc}
255
\begin{methoddesc}[FaultSystem]{addFault}{top, tag \optional{, bottom=None \optional{, w0_offsets=None\optional{, w1_max=None}}}}
adds the  fault \var{tag} to the fault system.

\var{top} is the list of the vertices defing the top of the fault
while \var{bottom} is the list of the vertices defing the bottom of the fault.
In the case of 2D \var{bottom} must not be present. Both list, if present, must have the same length.
\var{w1_max} defines the range of the $w\hackscore{1}$. If not present the mean value over the depth of
all segment edges in the fault is used.
\var{w0_offsets} sets the offsets $d^{ti}$. If not present it i chosen such that $d^{ti}-d^{t(i-1)}$ is the length of the $i$-th segment. In some cases, eg. when kinks in the fault are relevant, it can be useful
to explicitly specify the offsets in order to simplify the assignment of values.
\end{methoddesc}

256  \begin{methoddesc}[FaultSystem]{getMaxValue}{f\optional{, tol=1.e-8}}  \begin{methoddesc}[FaultSystem]{getMaxValue}{f\optional{, tol=1.e-8}}
257  returns the maximum value of \var{f}, the fault where the maximum is found and the location on the fault in fault coordinates. \var{f} must be a \Scalar. When the maximum is calculated only \DataSamplePoints are considered  returns the maximum value of \var{f}, the fault where the maximum is found and the location on the fault in fault coordinates. \var{f} must be a \Scalar. When the maximum is calculated only \DataSamplePoints are considered
258  which are on a fault in the fault system in the sense of condition~\ref{eq:2D line 3} or \ref{eq:3D line 3}, respectively. In the case no \DataSamplePoints is found the returned tag is \var{None} and  which are on a fault in the fault system in the sense of condition~\ref{eq:2D line 3} or \ref{eq:3D line 3}, respectively. In the case no \DataSamplePoints is found the returned tag is \var{None} and
# Line 153  together with a mask indicating where th Line 265  together with a mask indicating where th
265  \var{outside} is the value used as a replacement value for $w$ where the corresponding value in \var{x} is not  \var{outside} is the value used as a replacement value for $w$ where the corresponding value in \var{x} is not
266  on a fault. If not \var{outside} is not present an appropriate value is used.  on a fault. If not \var{outside} is not present an appropriate value is used.
267  \end{methoddesc}  \end{methoddesc}
268
269  \begin{methoddesc}[FaultSystem]{getSideAndDistance}{x,tag}  \begin{methoddesc}[FaultSystem]{getSideAndDistance}{x,tag}
270  returns the side and the distance at locations \var{x} from the fault \var{tag}.  returns the side and the distance at locations \var{x} from the fault \var{tag}.
271  \var{x} needs to be \Vector or \numpyNDA object. Positive values for side means that the corresponding location is  \var{x} needs to be \Vector or \numpyNDA object. Positive values for side means that the corresponding location is
# Line 161  to the right of the fault, a negative va Line 273  to the right of the fault, a negative va
273  to the left of the fault. The value zero means that the side is undefined.  to the left of the fault. The value zero means that the side is undefined.
274  \end{methoddesc}  \end{methoddesc}
275
276
277
278
279    \begin{methoddesc}[FaultSystem]{getFaultSegments}{tag}
280    returns the polylines used to describe fault \var{tag}. For \var{tag}=$t$ this is the list of the vertices
281    $[V^{ti}]$ for the 2D and the pair of lists of the top vertices $[V^{ti}]$ and the bottom vertices  $[v^{ti}]$ in 3D.
282    Note that the coordinates are represented as \numpyNDA objects.
283    \end{methoddesc}
284
286    strikes\optional{,
287    ls\optional{,
288    V0=[0.,0.,0.]\optional{,
289    tag=None\optional{,
290    dips=None\optional{,
291    depths= None\optional{,
292    w0_offsets=None\optional{,
293    w1_max=None}}}}}}}}
294    adds the  fault \var{tag} to the fault system.
295    \var{V0} defines the start point of fault names $t=$\var{tag}. The polyline
296    defining the fault segments on the surface are set
297    by the strike angles \var{strikes} (=$\sigma^{ti}$, north = $\pi/2$, the orientation is counter clockwise.) and
298    the length \var{ls} (=$l^{ti}$). In the 3D one also needs to define the
299    dip angles \var{dips} (=$\delta^{ti}$, vertical=$0$, right-hand rule applies.) and
300    the depth \var{depths} for each segment.
301    \var{w1_max} defines the range of the $w\hackscore{1}$. If not present the mean value over the depth of
302    all segment edges in the fault is used.
303    \var{w0_offsets} sets the offsets $\Omega^{ti}$. If not present it i chosen such that $\Omega^{ti}-\Omega^{t(i-1)}$ is the length of the $i$-th segment. In some cases, eg. when kinks in the fault are relevant, it can be useful
304    to explicitly specify the offsets in order to simplify the assignment of values.
305    \end{methoddesc}
306
307  \subsection{Example}  \subsection{Example}
308  See section~\ref{Slip CHAP}  See section~\ref{Slip CHAP}
309

Legend:
 Removed from v.2662 changed lines Added in v.2663