Diff of /trunk/doc/inversion/CostFunctions.tex

revision 4272 by gross, Fri Jan 18 03:35:15 2013 UTC revision 4273 by caltinay, Tue Mar 5 04:14:44 2013 UTC
# Line 57  while the susceptibility mapping uses th Line 57  while the susceptibility mapping uses th
57
58  \section{\class{InversionCostFunction} API}\label{chapter:ref:inversion cost function:api}  \section{\class{InversionCostFunction} API}\label{chapter:ref:inversion cost function:api}
59
60  The \class{InversionCostFunction} implements a \class{CostFunction} class used to run optimization solvers,  The \class{InversionCostFunction} implements a \class{CostFunction} class used
61  see section~\ref{chapter:ref:Minimization: costfunction class}.Its API is defined as follows:  to run optimization solvers, see Section~\ref{chapter:ref:Minimization: costfunction class}.
62    Its API is defined as follows:
63
64  \begin{classdesc}{InversionCostFunction}{regularization, mappings, forward_models}  \begin{classdesc}{InversionCostFunction}{regularization, mappings, forward_models}
65  Constructor for the inversion cost function. \member{regularization} sets the regularization to be used, see Chapter~\ref{Chp:ref:regularization}.  Constructor for the inversion cost function. \member{regularization} sets the regularization to be used, see Chapter~\ref{Chp:ref:regularization}.
66  \member{mappings} is a list of pairs where each pair comprises of a  \member{mappings} is a list of pairs where each pair comprises of a
67  physical parameter mapping (see Chapter~\ref{Chp:ref:mapping}) and an index which refers to the component of level set function  physical parameter mapping (see Chapter~\ref{Chp:ref:mapping}) and an index which refers to the component of level set function
68  defined by the \member{regularization} to be used to calculate the corresponding physical parameter. If  defined by the \member{regularization} to be used to calculate the corresponding physical parameter.
69  the level set function has a single component the index can be omitted. If in addition there is a single physical parameter  If the level set function has a single component the index can be omitted.
70  the mapping can be given instead of a list. \member{forward_models} is a list of pairs where the  If in addition there is a single physical parameter the mapping can be given instead of a list.
71  first pair component is a forward model ( see Chapter~\ref{Chp:ref:forward models}) and the second  \member{forward_models} is a list of pairs where the first pair component is a
72  pair component referring to the physical parameter in the \member{mappings} list providing the  physical parameter for the model.  forward model (see Chapter~\ref{Chp:ref:forward models}) and the second pair
73  If a single physical parameter is present the index can be omitted. If in addition a single  forward model is used this  component refers to the physical parameter in the \member{mappings} list
74  forward model can be assigned to \member{forward_models} in replacement of a list.  providing the physical parameter for the model.
75    If a single physical parameter is present the index can be omitted.
76    If in addition a single forward model is used this forward model can be
77    assigned to \member{forward_models} in replacement of a list.
78  \end{classdesc}  \end{classdesc}
79

80  \begin{methoddesc}[InversionCostFunction]{getDomain}{}  \begin{methoddesc}[InversionCostFunction]{getDomain}{}
81  returns the \escript domain of the inversion, see~\cite{ESCRIPT}.  returns the \escript domain of the inversion, see~\cite{ESCRIPT}.
82  \end{methoddesc}  \end{methoddesc}
83
85  returns the total number of trade-off factors. The count includes the trade-off factors $\mu^{data}_{f}$ for  returns the total number of trade-off factors.
86  the forward models and (hidden) trade-off fatcors in the regularization term, see~definition\ref{REF:EQU:DRIVE:10}.  The count includes the trade-off factors $\mu^{data}_{f}$ for the forward
87    models and (hidden) trade-off factors in the regularization term,
88    see Definition~\ref{REF:EQU:DRIVE:10}.
89  \end{methoddesc}  \end{methoddesc}
90
91  \begin{methoddesc}[InversionCostFunction]{getForwardModel}{\optional{idx=\None}}  \begin{methoddesc}[InversionCostFunction]{getForwardModel}{\optional{idx=\None}}
92  returns the forward model with index \member{idx}. If the cost function contains  returns the forward model with index \member{idx}.
93  on model only argument \member{idx} can be omitted.    If the cost function contains one model only argument \member{idx} can be omitted.
94  \end{methoddesc}  \end{methoddesc}
95
96  \begin{methoddesc}[InversionCostFunction]{getRegularization}{}  \begin{methoddesc}[InversionCostFunction]{getRegularization}{}
97  returns the regularization component of the cost function, see \class{regularization} in Chapter~\ref{Chp:ref:regularization}.  returns the regularization component of the cost function, see \class{regularization} in Chapter~\ref{Chp:ref:regularization}.
98  \end{methoddesc}  \end{methoddesc}
99

101  sets the trade-off factors  $\mu^{data}_{f}$ for the forward model components.  sets the trade-off factors $\mu^{data}_{f}$ for the forward model components.
102  If a single model is present \member{mu} must be a floating point numbers. Otherwise  If a single model is present \member{mu} must be a floating point number.
103  \member{mu} must be a list of floating point numbers. It is assumed that all  Otherwise \member{mu} must be a list of floating point numbers.
104  numbers are positive. Default values for the trade-off factors is one.  It is assumed that all numbers are positive.
105    The default value for all trade-off factors is one.
106  \end{methoddesc}  \end{methoddesc}
107
109  returns the values of the the trade-off factors  $\mu^{data}_{f}$ for the forward model components.  returns the values of the trade-off factors $\mu^{data}_{f}$ for the forward model components.
110  \end{methoddesc}  \end{methoddesc}
111

113  sets the trade of factors for the regularization component of the cost function.  sets the trade-off factors for the regularization component of the cost function.
114  for details. \member{mu} defines the trade-off factors for the level-set variation part and  \member{mu} defines the trade-off factors for the level-set variation part and
116  This method is a short-cut for calling \member{setTradeOffFactorsForVariation} and  This method is a shortcut for calling \member{setTradeOffFactorsForVariation}
118  Please see \class{Regularization} in Chapter~\ref{Chp:ref:regularization} for more details  regularization.
119  on the arguments \member{mu} and \member{mu_c}.  Please see \class{Regularization} in Chapter~\ref{Chp:ref:regularization} for
120    more details on the arguments \member{mu} and \member{mu_c}.
121  \end{methoddesc}  \end{methoddesc}
122
124  sets the trade-off factors for the forward model and regularization  sets the trade-off factors for the forward model and regularization terms.
125  terms. \member{mu} is a list of positive floats. The length of the list  \member{mu} is a list of positive floats. The length of the list is the total
127  first part of \member{mu} define the trade-off factors  $\mu^{data}_{f}$ for the forward model components  The first part of \member{mu} defines the trade-off factors $\mu^{data}_{f}$
128  while the remaining entries define the trade-off factors for the regularization components of the  for the forward model components while the remaining entries define the
129  cost function. By default all values are set to one.  trade-off factors for the regularization components of the cost function.
130    By default all values are set to one.
131  \end{methoddesc}  \end{methoddesc}
132
133  \begin{methoddesc}[InversionCostFunction]{getProperties}{m}  \begin{methoddesc}[InversionCostFunction]{getProperties}{m}
134  returns the physical properties from a given level set function \member{m}  returns the physical properties from a given level set function \member{m}
135  using the mappings of the cost function. The physical properties are  using the mappings of the cost function. The physical properties are
136  returned in the order in which they are given in the \member{mappings} argument  returned in the order in which they are given in the \member{mappings} argument
137  in the class constructor.  in the class constructor.
138  \end{methoddesc}  \end{methoddesc}
139
140  \begin{methoddesc}[InversionCostFunction]{createLevelSetFunction}{*props}  \begin{methoddesc}[InversionCostFunction]{createLevelSetFunction}{*props}
141  returns the level set function corresponding to set of given physical properties.  returns the level set function corresponding to set of given physical properties.
142  This method is the inverse of the \method{getProperties} method.  This method is the inverse of the \method{getProperties} method.
143  The arguments \member{props} define a tuple of values for the  physical properties  The arguments \member{props} define a tuple of values for the physical
144  where the order needs to correspond to the order in which the physical property mappings  properties where the order needs to correspond to the order in which the
145  are given in the \member{mappings} argument  physical property mappings are given in the \member{mappings} argument in the
146  in the class constructor. If a value for a physical property  class constructor. If a value for a physical property is given as \None the
147  is given as \None the corresponding component of the returned level set function is set to zero.  corresponding component of the returned level set function is set to zero.
148  If no physical properties are given all components of the level set function are set to zero.  If no physical properties are given all components of the level set function
149    are set to zero.
150  \end{methoddesc}  \end{methoddesc}
151
152  \begin{methoddesc}[InversionCostFunction]{getNorm}{m}  \begin{methoddesc}[InversionCostFunction]{getNorm}{m}
# Line 147  returns the norm of a level set function Line 154  returns the norm of a level set function
154  \end{methoddesc}  \end{methoddesc}
155
156  \begin{methoddesc}[InversionCostFunction]{getArguments}{m}  \begin{methoddesc}[InversionCostFunction]{getArguments}{m}
157  returns pre-computed values for the evaluation of the  returns pre-computed values for the evaluation of the cost function and its
158  cost function and its gradient for a given value \member{m}  gradient for a given value \member{m} of the level set function.
159  of the level set function. In essence the method collects  In essence the method collects pre-computed values for the underlying
160  pre-computed values for the underlying regularization and forward models\footnote{Using pre-computed  regularization and forward models\footnote{Using pre-computed values can
161  values can significant speed up the optimization process when the value  significantly speed up the optimization process when the value of the cost
162  of the cost function and it gradient for the same same leve set function  function and its gradient are needed for the same level set function.}.
are needed.}.
163  \end{methoddesc}  \end{methoddesc}
164
165  \begin{methoddesc}[InversionCostFunction]{getValue}{m \optional{, *args}}  \begin{methoddesc}[InversionCostFunction]{getValue}{m\optional{, *args}}
166  returns the value of the cost function for a given level set function \member{m}  returns the value of the cost function for a given level set function \member{m}
167  and corresponding pre-computed values \member{args}. If no pre-computed values are present  and corresponding pre-computed values \member{args}.
168  \member{getArguments} is called.  If the pre-computed values are not supplied \member{getArguments} is called.
169  \end{methoddesc}  \end{methoddesc}
170
172  returns the gradient of the cost function  at level set function \member{m}  returns the gradient of the cost function at level set function \member{m}
173  using the corresponding pre-computed values \member{args}. If no pre-computed values are present  using the corresponding pre-computed values \member{args}.
174  \member{getArguments} is called. The gradient  If the pre-computed values are not supplied \member{getArguments} is called.
175  is represented as a tuple $(Y,X)$ where in essence  The gradient is represented as a tuple $(Y,X)$ where in essence $Y$ represents
176  $Y$ represents the derivative of the cost function kernel with respect to the  the derivative of the cost function kernel with respect to the level set
177  level set function and $X$ represents thederivative of the cost function kernel with respect to the gradient of the  function and $X$ represents the derivative of the cost function kernel with
178  level set function, see Section~\ref{chapter:ref:inversion cost function:gradient} for more details.  respect to the gradient of the level set function, see
179    Section~\ref{chapter:ref:inversion cost function:gradient} for more details.
180  \end{methoddesc}  \end{methoddesc}
181
182  \begin{methoddesc}[InversionCostFunction]{getDualProduct}{m, g}  \begin{methoddesc}[InversionCostFunction]{getDualProduct}{m, g}
183  return the dual product of a level set function \member{m}  returns the dual product of a level set function \member{m} with a gradient
184  with a gradient \member{g}, see Section~\ref{chapter:ref:inversion cost function:gradient} for more details.  \member{g}, see Section~\ref{chapter:ref:inversion cost function:gradient} for more details.
185  This method uses the dual product of the regularization.  This method uses the dual product of the regularization.
186  \end{methoddesc}  \end{methoddesc}
187
188  \begin{methoddesc}[InversionCostFunction]{getInverseHessianApproximation}{m, g \optional{, *args}}  \begin{methoddesc}[InversionCostFunction]{getInverseHessianApproximation}{m, g \optional{, *args}}
189  returns an approximative evaluation of the inverse of the Hessian operator of the cost function  returns an approximative evaluation of the inverse of the Hessian operator of
190  for a given gradient \member{g} at a given level set function \member{m}  the cost function for a given gradient \member{g} at a given level set function
191  using the corresponding pre-computed values \member{args}. If no pre-computed values are present  \member{m} using the corresponding pre-computed values \member{args}.
192  \member{getArguments} is called. In the current implementation  If no pre-computed values are present \member{getArguments} is called.
193  contributions to Hessian operator from the forward models are ignored and only contributions  In the current implementation contributions to the Hessian operator from the
194  from the regularization and cross-gradient term.  forward models are ignored and only contributions from the regularization and