/[escript]/branches/doubleplusgood/doc/inversion/Drivers.tex
ViewVC logotype

Contents of /branches/doubleplusgood/doc/inversion/Drivers.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 4345 - (show annotations)
Fri Mar 29 07:09:41 2013 UTC (5 years, 11 months ago) by jfenwick
File MIME type: application/x-tex
File size: 12481 byte(s)
Spelling fixes
1 \section{Driver Classes}\label{chapter:ref:Drivers:Drivers}
2 The inversion minimizes an appropriate cost function $J$ to find the physical parameter distribution
3 (or more precisely the level set function) which gives the best fit to measured data. A
4 particular inversion case (gravity, magnetic or joint) is managed through
5 an instance of a specialization of the \class{InversionDriver} class. The task of the class instance
6 is to set up the appropriate cost function, to manage solution parameters and to run the optimization process.
7
8 \subsection{Template}
9 \begin{classdesc*}{InversionDriver}
10 template for inversion drivers.
11 \end{classdesc*}
12
13 \begin{methoddesc}[InversionDriver]{getCostFunction}{}
14 returns the cost function of the inversion. This will be an instance of the \class{InversionCostFunction} class, see Section~\ref{chapter:ref:inversion cost function}.
15 Use this method to access or alter attributes or call methods of the underlying cost function.
16 \end{methoddesc}
17
18 \begin{methoddesc}[InversionDriver]{getSolver}{}
19 returns the instance of the solver class used to minimize the cost function, see Chapter~\ref{chapter:ref:Minimization}.
20 Use this method to modify solver options.
21 \end{methoddesc}
22
23 \begin{methoddesc}[InversionDriver]{getDomain}{}
24 returns the domain of the inversion as an \escript \class{Domain} object.
25 \end{methoddesc}
26
27
28 \begin{methoddesc}[InversionDriver]{setSolverMaxIterations}{\optional{maxiter=\None}}
29 sets the maximum number of iteration steps for the solver used to minimize the cost function. The default value is 200.
30 If the maximum number is reached, the iteration will be terminated and \exception{MinimizerMaxIterReached} is thrown.
31 \end{methoddesc}
32
33 \begin{methoddesc}[InversionDriver]{setSolverTolerance}{\optional{m_tol=\None} \optional{, J_tol=\None}}
34 set the tolerance for the solver used to minimize the cost function. If \member{m_tol} is set the iteration is terminated
35 if the relative change of the level set function is less than or equal \member{m_tol}, see condition~\ref{EQU:MIN:3a}.
36 If \member{J_tol} is set the iteration is terminated if the change of the cost
37 function relative to the initial value is less than or equal \member{J_tol}, , see condition~\ref{EQU:MIN:3b}.
38 If both tolerances are set both stopping criteria need to be met.
39 By default \member{tol}=1e-4 and \member{J_tol}=\None.
40 \end{methoddesc}
41
42 \begin{methoddesc}[InversionDriver]{getLevelSetFunction}{}
43 returns the level set function as solution of the optimization problem.
44 This method can only be called if the optimization process as been completed.
45 If the iteration failed the last available approximation of the solution is returned.
46 \end{methoddesc}
47
48 \begin{methoddesc}[InversionDriver]{run}{}
49 this method runs the optimization solver and returns the physical parameter(s)
50 from the output of the inversion. Notice that the \method{setup} method must be
51 called before the first call of \method{run}.
52 The call can fail as the maximum number of iterations is reached in which case
53 a \exception{MinimizerMaxIterReached} exception is thrown or as there is an
54 incurable break down in the iteration in which case a \exception{MinimizerIterationIncurableBreakDown} exception is thrown.
55 \end{methoddesc}
56
57 \subsection{Gravity Inversion Driver}
58 For examples of usage please see Chapter~\ref{Chp:cook:gravity inversion}.
59
60 \begin{classdesc}{GravityInversion}{\optional{solverclass=None}
61 \optional{, fixGravityPotentialAtBottom=False}
62 }
63 Driver class to perform an inversion of Gravity (Bouguer) anomaly data.
64 This class is a sub-class of \class{InversionDriver}. The class uses the
65 standard \class{Regularization} for a single level set function,
66 see Chapter~\ref{Chp:ref:regularization}, \class{DensityMapping} mapping,
67 see Section~\ref{Chp:ref:mapping density}, and the gravity forward model
68 \class{GravityModel}, see Section~\ref{sec:forward gravity}.
69 \member{solverclass} set the solver class to be used for inversion,
70 see Chapter~\ref{chapter:ref:Minimization}.
71 By default the limited-memory Broyden-Fletcher-Goldfarb-Shanno (\emph{L-BFGS})~\cite{Nocedal1980}\index{L-BFGS} solver is used.
72 If \member{fixGravityPotentialAtBottom} is set \optional{, fixGravityPotentialAtBottom=False}to \True the gravity potential at the bottom is set to zero.
73 \end{classdesc}
74
75 \begin{methoddesc}[GravityInversion]{fixGravityPotentialAtBottom}{\optional{status=\True}}
76 If \member{status} is \True the gravity potential at the bottom is set to zero. Otherwise the gravity
77 potential at the top is set to zero only.
78 \end{methoddesc}
79
80 \begin{methoddesc}[GravityInversion]{setup}{
81 domainbuilder
82 \optional{, rho0=\None}
83 \optional{, drho=\None}
84 \optional{, z0=\None}
85 \optional{, beta=\None}
86 \optional{, w0=\None}
87 \optional{, w1=\None}
88 \optional{, rho_at_depth=\None}
89 }
90
91 sets up the inversion from an instance \member{domainbuilder} of a \class{DomainBuilder}, see Section~\ref{Chp:ref:domain builder}.
92 Only gravitational data attached to the \member{domainbuilder} are considered in the inversion.
93 \member{rho0} defines a reference density anomaly (default is 0),
94 \member{drho} defines a density anomaly (default is $2750 \frac{kg}{m^3}$),
95 \member{z0} defines the depth weighting reference depth (default is \None), and
96 \member{beta} defines the depth weighting exponent (default is \None),
97 see \class{DensityMapping} in Section~\ref{Chp:ref:mapping density}.
98 \member{w0} and \member{w1} define the weighting factors
99 $\omega^{(0)}$ and
100 $\omega^{(1)}$, respectively (see Equation~\ref{EQU:REG:1}).
101 By default \member{w0}=\None and \member{w1}=1 are used.
102 \member{rho_at_depth} sets the value for density at depth. This is only used if density is fixed below a certain depth,
103 see \class{Domain Builder} in Section~\ref{Chp:ref:domain builder}.
104 \end{methoddesc}
105
106 \begin{methoddesc}[GravityInversion]{setInitialGuess}{\optional{rho=\None}}
107 sets an initial guess for the density anomaly. By default zero is used.
108 \end{methoddesc}
109
110 \subsection{Magnetic Inversion Driver}
111 For examples of usage please see Chapter~\ref{Chp:cook:magnetic inversion}.
112
113 \begin{classdesc}{MagneticInversion}{\optional{solverclass=None}
114 }
115 Driver class to perform an inversion of magnetic anomaly data. This class
116 is a sub-class of \class{InversionDriver}. The class uses the standard
117 \class{Regularization} class for a single level set function, see Chapter~\ref{Chp:ref:regularization},
118 \class{SusceptibilityMapping} mapping, see Section~\ref{Chp:ref:mapping susceptibility}, and the linear
119 magnetic forward model \class{MagneticModel}, see Section~\ref{sec:forward magnetic}.
120 \member{solverclass} set the solver class to be used for inversion,
121 see Chapter~\ref{chapter:ref:Minimization}.
122 By default the limited-memory Broyden-Fletcher-Goldfarb-Shanno (\emph{L-BFGS})~\cite{Nocedal1980}\index{L-BFGS} solver is used.
123
124 \end{classdesc}
125
126 \begin{methoddesc}[MagneticInversion]{fixMagneticPotentialAtBottom}{\optional{status=\True}}
127 If \member{status} is \True the magnetic potential at the bottom is set to zero. Otherwise the magnetic
128 potential at the top is set to zero only.
129 \end{methoddesc}
130
131
132
133 \begin{methoddesc}[MagneticInversion]{setup}{
134 domainbuilder
135 \optional{, k0=\None}
136 \optional{, dk=\None}
137 \optional{, z0=\None}
138 \optional{, beta=\None}
139 \optional{, w0=\None}
140 \optional{, w1=\None}
141 \optional{, k_at_depth=\None}
142 }
143
144 sets up the inversion from an instance \member{domainbuilder} of a \class{DomainBuilder}, see Section~\ref{Chp:ref:domain builder}.
145 Only magnetic data attached to the \member{domainbuilder} are considered in the inversion.
146 \member{k0} defines a reference susceptibility anomaly (default is $0$),
147 \member{dk} defines a susceptibility anomaly scale (default is $1$),
148 \member{z0} defines the depth weighting reference depth (default is \None), and
149 \member{beta} defines the depth weighting exponent (default is \None),
150 see \class{SusceptibilityMapping} in Section~\ref{Chp:ref:mapping susceptibility}.
151 \member{w0} and \member{w1} define the weighting factors
152 $\omega^{(0)}$ and
153 $\omega^{(1)}$, respectively (see equation~\ref{EQU:REG:1}).
154 By default \member{w0}=\None and \member{w1}=1 are used.
155 \member{k_at_depth} sets the value for susceptibility at depth. This is only used if susceptibility is fixed below a certain depth,
156 see \class{Domain Builder} in Section~\ref{Chp:ref:domain builder}.
157 \end{methoddesc}
158
159 \begin{methoddesc}[MagneticInversion]{setInitialGuess}{\optional{k=\None}}
160 sets an initial guess for the susceptibility anomaly. By default zero is used.
161 \end{methoddesc}
162
163 \subsection{Gravity and Magnetic Joint Inversion Driver}
164 For examples of usage please see Chapter~\ref{Chp:cook:joint inversion}.
165
166 \begin{classdesc}{JointGravityMagneticInversion}{\optional{solverclass=None}
167 }
168 Driver class to perform a joint inversion of Gravity (Bouguer) and magnetic anomaly data.
169 This class is a sub-class of \class{InversionDriver}.
170 The class uses the standard \class{Regularization} for two level set functions
171 with cross-gradient correlation, see Chapter~\ref{Chp:ref:regularization},
172 \class{DensityMapping} and \class{SusceptibilityMapping} mappings, see Section~\ref{Chp:ref:mapping}, the
173 gravity forward model \class{GravityModel}, see Section~\ref{sec:forward gravity}
174 and the linear
175 magnetic forward model \class{MagneticModel}, see Section~\ref{sec:forward magnetic}.
176 \member{solverclass} set the solver class to be used for inversion,
177 see Chapter~\ref{chapter:ref:Minimization}.
178 By default the limited-memory Broyden-Fletcher-Goldfarb-Shanno (\emph{L-BFGS})~\cite{Nocedal1980}\index{L-BFGS} solver is used.
179 \end{classdesc}
180
181 \begin{methoddesc}[JointGravityMagneticInversion]{fixGravityPotentialAtBottom}{\optional{status=\True}}
182 If \member{status} is \True the gravity potential at the bottom is set to zero. Otherwise the gravity
183 potential at the top is set to zero only.
184 \end{methoddesc}
185
186
187 \begin{methoddesc}[JointGravityMagneticInversion]{fixMagneticPotentialAtBottom}{\optional{status=\True}}
188 If \member{status} is \True the magnetic potential at the bottom is set to zero. Otherwise the magnetic
189 potential at the top is set to zero only.
190 \end{methoddesc}
191
192 \begin{methoddesc}[JointGravityMagneticInversion]{setup}{
193 domainbuilder
194 \optional{, rho0=\None}
195 \optional{, drho=\None}
196 \optional{, rho_z0=\None}
197 \optional{, rho_beta=\None}
198 \optional{, k0=\None}
199 \optional{, dk=\None}
200 \optional{, k_z0=\None}
201 \optional{, k_beta=\None}
202 \optional{, w0=\None}
203 \optional{, w1=\None}
204 \optional{, w_gc=\None}
205 \optional{, rho_at_depth=\None}
206 \optional{, k_at_depth=\None}
207 }
208
209 sets up the inversion from an instance \member{domainbuilder} of a \class{DomainBuilder}, see Section~\ref{Chp:ref:domain builder}.
210 Gravity and magnetic data attached to the \member{domainbuilder} are considered in the inversion.
211 \member{rho0} defines a reference density anomaly (default is $0$),
212 \member{drho} defines a density anomaly (default is $2750 \frac{kg}{m^3}$),
213 \member{rho_z0} defines the depth weighting reference depth for density (default is \None), and
214 \member{rho_beta} defines the depth weighting exponent for density (default is \None),
215 see \class{DensityMapping} in Section~\ref{Chp:ref:mapping density}.
216 \member{k0} defines a reference susceptibility anomaly (default is $0$),
217 \member{dk} defines a susceptibility anomaly scale (default is $1$),
218 \member{k_z0} defines the depth weighting reference depth for susceptibility (default is \None), and
219 \member{k_beta} defines the depth weighting exponent for susceptibility (default is \None),
220 see \class{SusceptibilityMapping} in Section~\ref{Chp:ref:mapping susceptibility}.
221 \member{w0} and \member{w1} define the weighting factors
222 $\omega^{(0)}$ and
223 $\omega^{(1)}$, respectively (see Equation~\ref{EQU:REG:1}).
224 \member{w_gc} sets the weighting factor $\omega^{(c)}$ for the cross gradient term.
225 By default \member{w0}=\None, \member{w1}=1 and \member{w_gc}=1 are used.
226 \member{k_at_depth} sets the value for susceptibility at depth. This is only used if susceptibility is fixed below a certain depth,
227 see \class{Domain Builder} in Section~\ref{Chp:ref:domain builder}.
228 \member{rho_at_depth} sets the value for density at depth. This is only used if density is fixed below a certain depth,
229 see \class{Domain Builder} in Section~\ref{Chp:ref:domain builder}.
230 \end{methoddesc}
231
232 \begin{methoddesc}[JointGravityMagneticInversion]{setInitialGuess}{\optional{rho=\None, } \optional{k=\None}}
233 sets initial guesses for density and susceptibility anomaly.
234 By default zero is used for both.
235 \end{methoddesc}
236

  ViewVC Help
Powered by ViewVC 1.1.26