# Contents of /trunk/doc/inversion/CostFunctions.tex

Revision 4131 - (show annotations)
Fri Jan 11 03:54:16 2013 UTC (6 years, 7 months ago) by gross
Original Path: trunk/doc/inversion/Drivers.tex
File MIME type: application/x-tex
File size: 9768 byte(s)
documentaion of inversion driver API added.

 1 2 \chapter{Inversion Drivers}\label{chapter:ref:Drivers} 3 4 \section{Driver Classes} 5 The inversion minimizes an appropriate cost function $J$ to find the physical parameter distribution 6 (or more precisely the level set function) which gives the best fit to measured data. A 7 particular inversion case (gravity, magnetic or joint) is managed through 8 an instance of a specialization of the \class{InversionDriver} class. The task of the class instance 9 is to set up the appropriate cost function, to manage solution parameters and to run the optimization process. 10 11 \subsection{Template} 12 \begin{classdesc*}{InversionDriver} 13 template for inversion drivers. By default the limited-memory Broyden-Fletcher-Goldfarb-Shanno (\emph{L-BFGS})~\cite{L-BFGS}\index{L-BFGS} solver is used. 14 \end{classdesc*} 15 16 \begin{methoddesc}[InversionDriver]{getCostFunction}{} 17 returns the cost function of the inversion. This will be an instance of the \class{InversionCostFunction} class, see section~\ref{XXX}. 18 Use this method to access or alter attribute or methods of the underlying cost function. 19 \end{methoddesc} 20 21 \begin{methoddesc}[InversionDriver]{getDomain}{} 22 returns the domain of the inversion as an \escript \class{Domain} object. 23 \end{methoddesc} 24 25 26 \begin{methoddesc}[InversionDriver]{setSolverMaxIterations}{\optional{maxiter=\None}} 27 set the maximum number of iteration steps for the solver used to minimize the cost function. The default value is 200. 28 If the maximum number is reached, the iteration will be terminated and the \exception{MinimizerMaxIterReached} is thrown. 29 \end{methoddesc} 30 31 \begin{methoddesc}[InversionDriver]{setSolverTolerance}{\optional{tol=\None} \optional{, atol=\None}} 32 set the tolerance for the the solver used to minimize the cost function. If \member{tol} is set the iteration is terminated 33 if the relative change of the level set function is less or equal \member{tol}. 34 If \member{atol} is set the iteration is terminated 35 if the change of the cost function relative to the initial value is less or equal \member{atol}. If both 36 tolerances are set both stopping criteria need to be meet. By default \member{tol}=1e-4 and \member{atol}=\None. 37 \end{methoddesc} 38 39 \begin{methoddesc}[InversionDriver]{getLevelSetFunction}{} 40 returns the level set function as solution of the optimization problem. This method can only be called if the 41 optimization process as been completed. If the iteration failed the last available approximation of the 42 solution is returned. 43 \end{methoddesc} 44 45 \begin{methoddesc}[InversionDriver]{run}{} 46 this method run the optimization solver and returns the physical parameter(s) 47 from the output of the inversion. Notice that the \method{setup} method must be called before the first call 48 of \method{run}. 49 The call can fail as the maximum number is reached in which case 50 an \exception{MinimizerMaxIterReached} exception is thrown or as there is an incurable break down in the 51 iteration in which case an \exception{MinimizerIterationIncurableBreakDown} exception is thrown. 52 \end{methoddesc} 53 54 \subsection{Gravity Inversion Driver} 55 For examples of usage please see Chapter~\ref{Chp:cook:gravity inversion}. 56 57 \begin{classdesc}{GravityInversion}{} 58 Driver class to perform an inversion of Gravity (Bouguer) anomaly data. This class 59 is a sub-class of the \class{InversionDriver} class. The class uses the standard 60 \class{Regularization} class for a single level set function, see Chapter~\ref{Chp:ref:regularization}, 61 \class{DensityMapping} mapping, see Section~\ref{Chp:ref:mapping density}, and the 62 gravity forward model \class{GravityModel}, see Section~\ref{sec:forward gravity}. 63 \end{classdesc} 64 65 \begin{methoddesc}[GravityInversion]{setup}{ 66 domainbuilder 67 \optional{, rho0=\None} 68 \optional{, drho=\None} 69 \optional{, z0=\None} 70 \optional{, beta=\None} 71 \optional{, w0=\None} 72 \optional{, w1=\None}} 73 sets up the inversion from an instance \member{domainbuilder} of a \class{DomainBuilder}, see Section~\ref{Chp:ref:domain builder}. 74 Only gravitational data attached to the \member{domainbuilder} are considered in the inversion. 75 \member{rho0} defines a reference density anomaly (defaults is 0), 76 \member{drho} defines a density anomaly (defaults is $2750 \frac{kg}{m^3}$), 77 \member{z0} defines the depth weighting reference depth (defaults is \None), and 78 \member{beta} defines the depth weighting exponent (defaults is \None), 79 see \class{DensityMapping} in Section~\ref{Chp:ref:mapping density}. 80 \member{w0} and \member{w1} define the weighting factors 81 $\omega^{(0)}$ and 82 $\omega^{(1)}$, respectively (see equation~\ref{EQU:REG:1}). 83 As default \member{w0}=\None and \member{w1}=1 are used. 84 \end{methoddesc} 85 86 \begin{methoddesc}[GravityInversion]{setInitialGuess}{\optional{rho=\None}} 87 set an initial guess for the density anomaly. As default zero is used. 88 \end{methoddesc} 89 90 \subsection{Magnetic Inversion Driver} 91 For examples of usage please see Chapter~\ref{Chp:cook:magnetic inversion}. 92 93 94 \begin{classdesc}{MagneticInversion}{} 95 Driver class to perform an inversion of magnetic anomaly data. This class 96 is a sub-class of the \class{InversionDriver} class. The class uses the standard 97 \class{Regularization} class for a single level set function, see Chapter~\ref{Chp:ref:regularization}, 98 \class{SusceptibilityMapping} mapping, see Section~\label{Chp:ref:mapping susceptibility}, and the linear 99 magnetic forward model \class{MagneticModel}, see Section~\ref{sec:forward magnetic}. 100 \end{classdesc} 101 102 103 \begin{methoddesc}[MagneticInversion]{setup}{ 104 domainbuilder 105 \optional{, k0=\None} 106 \optional{, dk=\None} 107 \optional{, z0=\None} 108 \optional{, beta=\None} 109 \optional{, w0=\None} 110 \optional{, w1=\None}} 111 112 sets up the inversion from an instance \member{domainbuilder} of a \class{DomainBuilder}, see Section~\ref{Chp:ref:domain builder}. 113 Only magnetic data attached to the \member{domainbuilder} are considered in the inversion. 114 \member{k0} defines a reference susceptibility anomaly (defaults is 0), 115 \member{dk} defines a susceptibility anomaly scale (defaults is $1$), 116 \member{z0} defines the depth weighting reference depth (defaults is \None), and 117 \member{beta} defines the depth weighting exponent (defaults is \None), 118 see \class{SusceptibilityMapping} in Section~\ref{Chp:ref:mapping susceptibility}. 119 \member{w0} and \member{w1} define the weighting factors 120 $\omega^{(0)}$ and 121 $\omega^{(1)}$, respectively (see equation~\ref{EQU:REG:1}). 122 As default \member{w0}=\None and \member{w1}=1 are used. 123 \end{methoddesc} 124 125 \begin{methoddesc}[MagneticInversion]{setInitialGuess}{\optional{k=\None}} 126 set an initial guess for the susceptibility anomaly. As default zero is used. 127 \end{methoddesc} 128 129 \subsection{Gravity and Magnetic Joint Inversion Driver} 130 For examples of usage please see Chapter~\ref{Chp:cook:joint inversion}. 131 132 \begin{classdesc}{JointGravityMagneticInversion}{} 133 Driver class to perform a joint inversion of Gravity (Bouguer) and magnetic anomaly data. This class 134 is a sub-class of the \class{InversionDriver} class. 135 The class uses the standard 136 \class{Regularization} class for a two level set functions with cross-gradient correlation, see Chapter~\ref{Chp:ref:regularization}, 137 \class{DensityMapping} and \class{SusceptibilityMapping} mappings, see Section~\ref{Chp:ref:mapping}, the 138 gravity forward model \class{GravityModel}, see Section~\ref{sec:forward gravity} 139 and the linear 140 magnetic forward model \class{MagneticModel}, see Section~\ref{sec:forward magnetic}. 141 \end{classdesc} 142 143 144 \begin{methoddesc}[JointGravityMagneticInversion]{setup}{ 145 domainbuilder 146 \optional{, rho0=\None} 147 \optional{, drho=\None} 148 \optional{, rho_z0=\None} 149 \optional{, rho_beta=\None} 150 \optional{, k0=\None} 151 \optional{, dk=\None} 152 \optional{, k_z0=\None} 153 \optional{, k_beta=\None} 154 \optional{, w0=\None} 155 \optional{, w1=\None} 156 \optional{, w_gc=\None} 157 } 158 sets up the inversion from an instance \member{domainbuilder} of a \class{DomainBuilder}, see Section~\ref{Chp:ref:domain builder}. 159 Gravity and magnetic data attached to the \member{domainbuilder} are considered in the inversion. 160 \member{rho0} defines a reference density anomaly (defaults is 0), 161 \member{drho} defines a density anomaly (defaults is $2750 \frac{kg}{m^3}$), 162 \member{rho_z0} defines the depth weighting reference depth for density (defaults is \None), and 163 \member{rho_beta} defines the depth weighting exponent for density (defaults is \None), 164 see \class{DensityMapping} in Section~\ref{Chp:ref:mapping density}. 165 \member{k0} defines a reference susceptibility anomaly (defaults is 0), 166 \member{dk} defines a susceptibility anomaly scale (defaults is $1$), 167 \member{k_z0} defines the depth weighting reference depth for susceptibility (defaults is \None), and 168 \member{k_beta} defines the depth weighting exponent for susceptibility (defaults is \None), 169 see \class{SusceptibilityMapping} in Section~\ref{Chp:ref:mapping susceptibility}. 170 \member{w0} and \member{w1} define the weighting factors 171 $\omega^{(0)}$ and 172 $\omega^{(1)}$, respectively (see equation~\ref{EQU:REG:1}). 173 \member{w_gc} sets the weighting factor $\omega^{(c)}$ for the cross gradient term. 174 As default \member{w0}=\None, \member{w1}=1 and \member{w_gc}=1 are used. 175 \end{methoddesc} 176 177 \begin{methoddesc}[JointGravityMagneticInversion]{setInitialGuess}{\optional{rho=None, } \optional{k=\None}} 178 set initial guesses for density and susceptibility anomaly. As default zeros are used. 179 \end{methoddesc} 180 181 182 183 \section{Inversion Cost Function} 184 185 186 =========== 187 \begin{classdesc}{SimpleCostFunction}{regularization, mapping, forwardmodel} 188 This is a simple cost function with a single continuous (mapped) variable. 189 It is the sum of two weighted terms, a single forward model and a single 190 regularization term. This cost function is used by the provided gravity 191 and magnetic inversion implementations. 192 \end{classdesc}