 # Diff of /trunk/downunder/py_src/costfunctions.py

revision 4096 by caltinay, Wed Dec 5 05:32:22 2012 UTC revision 4097 by caltinay, Fri Dec 7 01:18:35 2012 UTC
# Line 37  class CostFunction(object): Line 37  class CostFunction(object):
37          f=cf.getValue(x, *args)          f=cf.getValue(x, *args)
38          # ... it could be required to update x without using the gradient...          # ... it could be required to update x without using the gradient...
39          # ... but then ...          # ... but then ...
40          gf=cf.getGradient(x, *args)          gf=cf.getGradient(x, *args)
41
42      The class distinguishes between the representation of the solution      The class distinguishes between the representation of the solution
43      x (x-type) and the gradients (r-type).      x (x-type) and the gradients (r-type).
44
45      :cvar provides_inverse_Hessian_approximation: This member should be set      :cvar provides_inverse_Hessian_approximation: This member should be set
46              to ``True`` in subclasses that provide a valid implementation of              to ``True`` in subclasses that provide a valid implementation of
# Line 60  class CostFunction(object): Line 60  class CostFunction(object):
60          returns precalculated values that are shared in the calculation of          returns precalculated values that are shared in the calculation of
61          *f(x)* and *grad f(x)* and the Hessian operator. The default          *f(x)* and *grad f(x)* and the Hessian operator. The default
62          implementation returns an empty tuple.          implementation returns an empty tuple.
63
64          :param x: location of derivative          :param x: location of derivative
65          :type x: x-type          :type x: x-type
66          :rtype: ``tuple``          :rtype: ``tuple``
67          """          """
68          return ()          return ()
69
70      def getDualProduct(self, x, r):      def getDualProduct(self, x, r):
71          """          """
72          returns the dual product of ``x`` and ``r``          returns the dual product of ``x`` and ``r``
73
74          :type x: x-type          :type x: x-type
75          :type r: r-type          :type r: r-type
76          :rtype: ``float``          :rtype: ``float``
# Line 81  class CostFunction(object): Line 81  class CostFunction(object):
81          """          """
82          returns the gradient of *f* at *x* using the precalculated values for          returns the gradient of *f* at *x* using the precalculated values for
83          *x*.          *x*.
84
85          :param x: location of derivative          :param x: location of derivative
86          :type x: x-type          :type x: x-type
87          :param args: pre-calculated values for ``x`` from `getArguments()`          :param args: pre-calculated values for ``x`` from `getArguments()`
88          :rtype: r-type          :rtype: r-type
89          """          """
90          raise NotImplementedError          raise NotImplementedError
91
92      def getInverseHessianApproximation(self, x, r, *args):      def getInverseHessianApproximation(self, x, r, *args):
93          """          """
94          returns an approximative evaluation *p* of the inverse of the Hessian          returns an approximative evaluation *p* of the inverse of the Hessian
95          operator of the cost function for a given gradient *r* at a given          operator of the cost function for a given gradient *r* at a given
96          location *x*: *H(x) p = r*          location *x*: *H(x) p = r*
97
98          :param x: location of Hessian operator to be evaluated          :param x: location of Hessian operator to be evaluated
99          :type x: x-type          :type x: x-type
100          :param r: a given gradient          :param r: a given gradient
101          :type r: r-type          :type r: r-type
102          :param args: pre-calculated values for ``x`` from `getArguments()`          :param args: pre-calculated values for ``x`` from `getArguments()`
103          :rtype: x-type          :rtype: x-type
# Line 114  class CostFunction(object): Line 114  class CostFunction(object):
114      def getValue(self, x, *args):      def getValue(self, x, *args):
115          """          """
116          returns the value *f(x)* using the precalculated values for *x*.          returns the value *f(x)* using the precalculated values for *x*.
117
118          :param x: a solution approximation          :param x: a solution approximation
119          :type x: x-type          :type x: x-type
120          :rtype: ``float``          :rtype: ``float``
# Line 155  class MeteredCostFunction(CostFunction): Line 155  class MeteredCostFunction(CostFunction):
155          self.Gradient_calls=0          self.Gradient_calls=0
156          self.Arguments_calls=0          self.Arguments_calls=0
157          self.InverseHessianApproximation_calls=0          self.InverseHessianApproximation_calls=0
158
159      def getDualProduct(self, x, r):      def getDualProduct(self, x, r):
160          """          """
161          returns the dual product of ``x`` and ``r``          returns the dual product of ``x`` and ``r``
162
163          :type x: x-type          :type x: x-type
164          :type r: r-type          :type r: r-type
165          :rtype: ``float``          :rtype: ``float``
166          """          """
167          self.DualProduct_calls+=1          self.DualProduct_calls+=1
168          return self._getDualProduct(x, r)          return self._getDualProduct(x, r)
169
170      def _getDualProduct(self, x, r):      def _getDualProduct(self, x, r):
171          """          """
172          returns the dual product of ``x`` and ``r``          returns the dual product of ``x`` and ``r``
173
174          :type x: x-type          :type x: x-type
175          :type r: r-type          :type r: r-type
176          :rtype: ``float``          :rtype: ``float``
177          :note: This is the worker for `getDualProduct()`, needs to be overwritten.          :note: This is the worker for `getDualProduct()`, needs to be overwritten.
178          """          """
179          raise NotImplementedError          raise NotImplementedError
180
181      def getValue(self, x, *args):      def getValue(self, x, *args):
182          """          """
183          returns the value *f(x)* using the precalculated values for *x*.          returns the value *f(x)* using the precalculated values for *x*.
184
185          :param x: a solution approximation          :param x: a solution approximation
186          :type x: x-type          :type x: x-type
187          :rtype: ``float``          :rtype: ``float``
188          """          """
189          self.Value_calls+=1          self.Value_calls+=1
190          return self._getValue(x, *args)          return self._getValue(x, *args)
191
192      def _getValue(self, x, *args):      def _getValue(self, x, *args):
193          """          """
194          returns the value *f(x)* using the precalculated values for *x*.          returns the value *f(x)* using the precalculated values for *x*.
195
196          :param x: a solution approximation          :param x: a solution approximation
197          :type x: x-type          :type x: x-type
198          :rtype: ``float``          :rtype: ``float``
199          :note: This is the worker for ``getValue()``, needs to be overwritten.          :note: This is the worker for ``getValue()``, needs to be overwritten.
200          """          """
201          raise NotImplementedError          raise NotImplementedError
202
203      def getGradient(self, x, *args):      def getGradient(self, x, *args):
204          """          """
205          returns the gradient of *f* at *x* using the precalculated values for          returns the gradient of *f* at *x* using the precalculated values for
206          *x*.          *x*.
207
208          :param x: location of derivative          :param x: location of derivative
209          :type x: x-type          :type x: x-type
210          :param args: pre-calculated values for ``x`` from `getArguments()`          :param args: pre-calculated values for ``x`` from `getArguments()`
211          :rtype: r-type                  :rtype: r-type
212          """          """
213          self.Gradient_calls+=1          self.Gradient_calls+=1
214          return self._getGradient(x, *args)          return self._getGradient(x, *args)
# Line 217  class MeteredCostFunction(CostFunction): Line 217  class MeteredCostFunction(CostFunction):
217          """          """
218          returns the gradient of *f* at *x* using the precalculated values for          returns the gradient of *f* at *x* using the precalculated values for
219          *x*.          *x*.
220
221          :param x: location of derivative          :param x: location of derivative
222          :type x: x-type          :type x: x-type
223          :param args: pre-calculated values for ``x`` from `getArguments()`          :param args: pre-calculated values for ``x`` from `getArguments()`
224          :rtype: r-type            :rtype: r-type
225          :note: This is the worker for `getGradient()`, needs to be overwritten.          :note: This is the worker for `getGradient()`, needs to be overwritten.
226          """                """
227          raise NotImplementedError          raise NotImplementedError
228
229
230      def getArguments(self, x):      def getArguments(self, x):
231          """          """
232          returns precalculated values that are shared in the calculation of          returns precalculated values that are shared in the calculation of
233          *f(x)* and *grad f(x)* and the Hessian operator          *f(x)* and *grad f(x)* and the Hessian operator
234
235          :param x: location of derivative          :param x: location of derivative
236          :type x: x-type          :type x: x-type
237          """          """
238          self.Arguments_calls+=1          self.Arguments_calls+=1
239          return self._getArguments(x)          return self._getArguments(x)
240
241      def _getArguments(self, x):      def _getArguments(self, x):
242          """          """
243          returns precalculated values that are shared in the calculation of          returns precalculated values that are shared in the calculation of
244          *f(x)* and *grad f(x)* and the Hessian operator          *f(x)* and *grad f(x)* and the Hessian operator
245
246          :param x: location of derivative          :param x: location of derivative
247          :type x: x-type          :type x: x-type
248          :note: Overwrite this function to implement a specific cost function          :note: Overwrite this function to implement a specific cost function
249          """          """
250          return ()              return ()
251
252      def getInverseHessianApproximation(self, x, r,*args):      def getInverseHessianApproximation(self, x, r,*args):
253          """          """
254          returns an approximative evaluation *p* of the inverse of the Hessian          returns an approximative evaluation *p* of the inverse of the Hessian
255          operator of the cost function for a given gradient *r* at a given          operator of the cost function for a given gradient *r* at a given
256          location *x*: *H(x) p = r*          location *x*: *H(x) p = r*
257
258          :param x: location of Hessian operator to be evaluated.          :param x: location of Hessian operator to be evaluated.
259          :type x: x-type          :type x: x-type
260          :param r: a given gradient          :param r: a given gradient
261          :type r: r-type          :type r: r-type
262          :param args: pre-calculated values for ``x`` from `getArguments()`          :param args: pre-calculated values for ``x`` from `getArguments()`
263          :rtype: x-type          :rtype: x-type
264          :note: In general it is assumed that the Hessian *H(x)* needs to be calculate in each call for a new          :note: In general it is assumed that the Hessian *H(x)* needs to be
265            location *x*. However, the solver may suggest that this is not required, typically when the iteration                 calculate in each call for a new location *x*. However, the
266            ius close to completness.                 solver may suggest that this is not required, typically when
267                           the iteration is close to completeness.
268          """          """
269          self.InverseHessianApproximation_calls+=1          self.InverseHessianApproximation_calls+=1
270          return self._getInverseHessianApproximation(x, r, *args)          return self._getInverseHessianApproximation(x, r, *args)
271
272      def _getInverseHessianApproximation(self, x, r, *args):      def _getInverseHessianApproximation(self, x, r, *args):
273          """          """
274          returns an approximative evaluation *p* of the inverse of the Hessian operator of the costfunction          returns an approximative evaluation *p* of the inverse of the Hessian
275          for a given gradient type *r* at a given location *x*: *H(x) p = r*          operator of the cost function for a given gradient *r* at a given
276                    location *x*: *H(x) p = r*
277          :param x: location of Hessian operator to be evaluated.
278            :param x: location of Hessian operator to be evaluated
279          :type x: x-type          :type x: x-type
280          :param r: a given gradient          :param r: a given gradient
281          :type r: r-type          :type r: r-type
282          :param args: pre-calculated values for ``x`` from ``getArguments()``          :param args: pre-calculated values for ``x`` from `getArguments()`
283          :rtype: x-type          :rtype: x-type
284          :note: In general it is assumed that the Hessian *H(x)* needs to be          :note: In general it is assumed that the Hessian *H(x)* needs to be
285                 calculate in each call for a new location *x*. However, the                 calculate in each call for a new location *x*. However, the
286                 solver may suggest that this is not required, typically when                 solver may suggest that this is not required, typically when
287                 the iteration is close to completness.                 the iteration is close to completeness.
288          :note: This is the worker for getInverseHessianApproximation()`, needs          :note: This is the worker for getInverseHessianApproximation()`, needs
289                 to be overwritten.                 to be overwritten.
290          :note: Subclasses that implement this method should set the class          :note: Subclasses that implement this method should set the class

Legend:
 Removed from v.4096 changed lines Added in v.4097

 ViewVC Help Powered by ViewVC 1.1.26