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

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