GammaLib  1.7.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GOptimizerPar.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GOptimizerPar.hpp - Optimizer parameter class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2013-2016 by Juergen Knoedlseder *
5  * ----------------------------------------------------------------------- *
6  * *
7  * This program is free software: you can redistribute it and/or modify *
8  * it under the terms of the GNU General Public License as published by *
9  * the Free Software Foundation, either version 3 of the License, or *
10  * (at your option) any later version. *
11  * *
12  * This program is distributed in the hope that it will be useful, *
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
15  * GNU General Public License for more details. *
16  * *
17  * You should have received a copy of the GNU General Public License *
18  * along with this program. If not, see <http://www.gnu.org/licenses/>. *
19  * *
20  ***************************************************************************/
21 /**
22  * @file GOptimizerPar.hpp
23  * @brief Optimizer parameter class interface definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GOPTIMIZERPAR_HPP
28 #define GOPTIMIZERPAR_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <string>
32 #include <cmath>
33 #include "GBase.hpp"
34 #include "GXmlElement.hpp"
35 
36 
37 /***********************************************************************//**
38  * @class GOptimizerPar
39  *
40  * @brief Optimizer parameter class
41  *
42  * This class implements a function parameter for the optimizer. A function
43  * parameter is a numerical value that is used to describe a function.
44  *
45  * A function parameter has the following attributes:
46  * - @p value gives the numerical value of the parameter
47  * - @p error gives the statistical uncertainty in the parameter value
48  * - @p gradient gives the gradient of a function with respect to the
49  * parameter
50  * - @p min gives the minimum value that the parameter value can take
51  * - @p max gives the maximum value that the parameter value can take
52  *
53  * The parameter attributes are set and retrieved using the value(),
54  * error(), gradient(), min() and max() methods, respectively. Furthermore,
55  * the range() method is used to simultaneously set the minimum and maximum
56  * value of a parameter.
57  *
58  * The minimum and maximum values are optional, and existence of these
59  * attributes is tested using the has_min() and has_max() methods,
60  * respectively. The minimum value, maximum value are removed using the
61  * remove_min() and remove_max() methods. Simultaneous removal of minimum
62  * and maximum values is done using the remove_range() method.
63  *
64  * Each parameter has furthermore the following properties:
65  * - @p free specifies whether the parameter should be fitted
66  * - @p grad specifies whether the parameter gradient is computed
67  * analytically (true) or numerically (false)
68  *
69  * The parameter property @p free is set using the free() and fix()
70  * methods and it is retrieved using the is_free() and is_fixed() methods.
71  * The attribute @p grad is set and retrieved using the has has_grad()
72  * methods.
73  *
74  * Each function parameter is factorized into a @p factor and a @p scale
75  * term. The GOptimizerPar class stores the factors and the scale factor has
76  * data members, and the true values are computed using the following
77  * relations:
78  *
79  * value = m_factor_value * m_scale
80  * error = m_factor_error * m_scale
81  * gradient = m_factor_gradient * m_scale
82  * min = m_factor_min * m_scale
83  * max = m_factor_max * m_scale
84  *
85  * The @p factor and @p scale terms can be set and retrieved using the
86  * factor_value(), factor_error(), factor_gradient(), factor_min(),
87  * factor_max() and scale() methods.
88  ***************************************************************************/
89 class GOptimizerPar : public GBase {
90 
91 public:
92  // Constructors and destructors
93  GOptimizerPar(void);
94  GOptimizerPar(const std::string& name, const double& value);
95  GOptimizerPar(const std::string& name, const double& factor,
96  const double& scale);
97  GOptimizerPar(const GOptimizerPar& par);
98  virtual ~GOptimizerPar(void);
99 
100  // Operators
102 
103  // Attribute methods
104  double value(void) const;
105  double error(void) const;
106  double gradient(void) const;
107  double min(void) const;
108  double max(void) const;
109  void value(const double& value);
110  void error(const double& error);
111  void gradient(const double& gradient);
112  void min(const double& min);
113  void max(const double& max);
114  void range(const double& min, const double& max);
115 
116  // Factorization methods
117  const double& factor_value(void) const;
118  const double& factor_error(void) const;
119  const double& factor_gradient(void) const;
120  const double& factor_min(void) const;
121  const double& factor_max(void) const;
122  const double& scale(void) const;
123  void factor_value(const double& value);
124  void factor_error(const double& error);
125  void factor_gradient(const double& gradient) const;
126  void factor_min(const double& min);
127  void factor_max(const double& max);
128  void factor_range(const double& min, const double& max);
129  void scale(const double& scale);
130 
131  // Boundary methods
132  bool has_min(void) const;
133  bool has_max(void) const;
134  bool has_range(void) const;
135  void remove_min(void);
136  void remove_max(void);
137  void remove_range(void);
138 
139  // Property methods
140  bool is_free(void) const;
141  bool is_fixed(void) const;
142  bool has_grad(void) const;
143  void free(void);
144  void fix(void);
145  void has_grad(const bool& grad);
146 
147  // Other methods
148  void clear(void);
149  GOptimizerPar* clone(void) const;
150  std::string classname(void) const;
151  const std::string& name(void) const;
152  const std::string& unit(void) const;
153  void name(const std::string& name);
154  void unit(const std::string& unit);
155  void autoscale(void);
156  std::string print(const GChatter& chatter = NORMAL) const;
157 
158 protected:
159  // Protected methods
160  void init_members(void);
161  void copy_members(const GOptimizerPar& par);
162  void free_members(void);
163 
164  // Proteced data members
165  std::string m_name; //!< Parameter name
166  std::string m_unit; //!< Parameter unit
167  double m_factor_value; //!< Parameter value factor
168  double m_factor_error; //!< Uncertainty in parameter value factor
169  double m_factor_min; //!< Parameter minimum factor
170  double m_factor_max; //!< Parameter maximum factor
171  mutable double m_factor_gradient; //!< Function gradient factor
172  double m_scale; //!< Parameter scaling (true = factor * scale)
173  bool m_free; //!< Parameter is free
174  bool m_has_min; //!< Parameter has minimum boundary
175  bool m_has_max; //!< Parameter has maximum boundary
176  bool m_has_grad; //!< Parameter has analytic gradient
177 };
178 
179 
180 /***********************************************************************//**
181  * @brief Return class name
182  *
183  * @return String containing the class name ("GOptimizerPar").
184  ***************************************************************************/
185 inline
186 std::string GOptimizerPar::classname(void) const
187 {
188  return ("GOptimizerPar");
189 }
190 
191 
192 /***********************************************************************//**
193  * @brief Return parameter value
194  *
195  * @return Parameter value.
196  *
197  * Returns the parameter value. The parameter value is computed by
198  * multiplying the value factor by the scale factor.
199  ***************************************************************************/
200 inline
201 double GOptimizerPar::value(void) const
202 {
203  return (m_factor_value * m_scale);
204 }
205 
206 
207 /***********************************************************************//**
208  * @brief Return parameter error
209  *
210  * @return Parameter error.
211  *
212  * Returns the parameter error. The parameter error is computed by
213  * multiplying the error factor by the scale factor. By definition, the error
214  * is a positive number, hence the method returns the absolute value of the
215  * internally computed error.
216  ***************************************************************************/
217 inline
218 double GOptimizerPar::error(void) const
219 {
220  return std::abs(m_factor_error * m_scale);
221 }
222 
223 
224 /***********************************************************************//**
225  * @brief Return parameter gradient
226  *
227  * @return Parameter gradient.
228  *
229  * Returns the parameter gradient. The parameter gradient is computed by
230  * dividing the gradient factor by the scale factor. The method returns
231  * zero in case that the scale factor is zero.
232  ***************************************************************************/
233 inline
234 double GOptimizerPar::gradient(void) const
235 {
236  // The GOptimizerPar class makes sure that m_scale is never 0, so no test
237  // is needed here
238  return (m_factor_gradient / m_scale);
239 }
240 
241 
242 /***********************************************************************//**
243  * @brief Return parameter minimum boundary
244  *
245  * @return Parameter minimum boundary.
246  *
247  * Returns the parameter minimum boundary. The parameter minimum boundary is
248  * computed by multiplying the minimum boundary factor by the scale factor.
249  ***************************************************************************/
250 inline
251 double GOptimizerPar::min(void) const
252 {
253  return (m_factor_min * m_scale);
254 }
255 
256 
257 /***********************************************************************//**
258  * @brief Return parameter maximum boundary
259  *
260  * @return Parameter maximum boundary.
261  *
262  * Returns the parameter maximum boundary. The parameter maximum boundary is
263  * computed by multiplying the maximum boundary factor by the scale factor.
264  ***************************************************************************/
265 inline
266 double GOptimizerPar::max(void) const
267 {
268  return (m_factor_max * m_scale);
269 }
270 
271 
272 /***********************************************************************//**
273  * @brief Return parameter value factor
274  *
275  * @return Parameter value factor.
276  *
277  * Returns the parameter value factor.
278  ***************************************************************************/
279 inline
280 const double& GOptimizerPar::factor_value(void) const
281 {
282  return (m_factor_value);
283 }
284 
285 
286 /***********************************************************************//**
287  * @brief Return parameter error factor
288  *
289  * @return Parameter error factor.
290  *
291  * Returns the parameter error factor.
292  ***************************************************************************/
293 inline
294 const double& GOptimizerPar::factor_error(void) const
295 {
296  return (m_factor_error);
297 }
298 
299 
300 /***********************************************************************//**
301  * @brief Return parameter gradient factor
302  *
303  * @return Parameter gradient factor.
304  *
305  * Returns the parameter gradient factor.
306  ***************************************************************************/
307 inline
308 const double& GOptimizerPar::factor_gradient(void) const
309 {
310  return (m_factor_gradient);
311 }
312 
313 
314 /***********************************************************************//**
315  * @brief Return parameter minimum boundary factor
316  *
317  * @return Parameter minimum boundary factor.
318  *
319  * Returns the parameter minimum boundary factor.
320  ***************************************************************************/
321 inline
322 const double& GOptimizerPar::factor_min(void) const
323 {
324  return (m_factor_min);
325 }
326 
327 
328 /***********************************************************************//**
329  * @brief Return parameter maximum boundary factor
330  *
331  * @return Parameter maximum boundary factor.
332  *
333  * Returns the parameter maximum boundary factor.
334  ***************************************************************************/
335 inline
336 const double& GOptimizerPar::factor_max(void) const
337 {
338  return (m_factor_max);
339 }
340 
341 
342 /***********************************************************************//**
343  * @brief Return parameter scale
344  *
345  * @return Parameter scale factor.
346  *
347  * Returns the parameter scale factor.
348  ***************************************************************************/
349 inline
350 const double& GOptimizerPar::scale(void) const
351 {
352  return (m_scale);
353 }
354 
355 
356 /***********************************************************************//**
357  * @brief Set parameter error factor
358  *
359  * @param[in] error Parameter error factor.
360  *
361  * Sets the parameter error factor.
362  ***************************************************************************/
363 inline
364 void GOptimizerPar::factor_error(const double& error)
365 {
367  return;
368 }
369 
370 
371 /***********************************************************************//**
372  * @brief Set parameter gradient factor
373  *
374  * @param[in] gradient Parameter gradient factor.
375  *
376  * Sets the parameter gradient factor.
377  ***************************************************************************/
378 inline
379 void GOptimizerPar::factor_gradient(const double& gradient) const
380 {
382  return;
383 }
384 
385 
386 /***********************************************************************//**
387  * @brief Signal if parameter has minimum boundary
388  *
389  * @return True if parameter has minimum boundary, false otherwise.
390  *
391  * Signals if the parameter has a minimum boundary.
392  ***************************************************************************/
393 inline
394 bool GOptimizerPar::has_min(void) const
395 {
396  return m_has_min;
397 }
398 
399 
400 /***********************************************************************//**
401  * @brief Signal if parameter has maximum boundary
402  *
403  * @return True if parameter has maximum boundary, false otherwise.
404  *
405  * Signals if the parameter has a maximum boundary.
406  ***************************************************************************/
407 inline
408 bool GOptimizerPar::has_max(void) const
409 {
410  return m_has_max;
411 }
412 
413 
414 /***********************************************************************//**
415  * @brief Signal if parameter has minimum and maximum boundaries
416  *
417  * @return True if parameter has minimum and maximum boundaries, false
418  * otherwise.
419  *
420  * Signals if the parameter has a minimum and a maximum boundary.
421  ***************************************************************************/
422 inline
423 bool GOptimizerPar::has_range(void) const
424 {
425  return (m_has_min && m_has_max);
426 }
427 
428 
429 /***********************************************************************//**
430  * @brief Removes minimum boundary
431  *
432  * Removes minimum boundary from the parameter.
433  ***************************************************************************/
434 inline
436 {
437  m_has_min = false;
438  return;
439 }
440 
441 
442 /***********************************************************************//**
443  * @brief Removes maximum boundary
444  *
445  * Removes maximum boundary from the parameter.
446  ***************************************************************************/
447 inline
449 {
450  m_has_max = false;
451  return;
452 }
453 
454 
455 /***********************************************************************//**
456  * @brief Removes minimum and maximum boundary
457  *
458  * Removes minimum and maximum boundary from the parameter.
459  ***************************************************************************/
460 inline
462 {
463  m_has_min = false;
464  m_has_max = false;
465  return;
466 }
467 
468 
469 /***********************************************************************//**
470  * @brief Signal if parameter is free
471  *
472  * @return True if parameter is free, false otherwise.
473  *
474  * Signals if the parameter is free, i.e. that it shall be fitted in a
475  * parameter optimization process.
476  ***************************************************************************/
477 inline
478 bool GOptimizerPar::is_free(void) const
479 {
480  return m_free;
481 }
482 
483 
484 /***********************************************************************//**
485  * @brief Signal if parameter is fixed
486  *
487  * @return True if parameter is fixed, false otherwise.
488  *
489  * Signals if the parameter is fixed, i.e. that it shall NOT be fitted in a
490  * parameter optimization process.
491  ***************************************************************************/
492 inline
493 bool GOptimizerPar::is_fixed(void) const
494 {
495  return (!m_free);
496 }
497 
498 
499 /***********************************************************************//**
500  * @brief Signal if parameter gradient is computed analytically
501  *
502  * @return True if parameter is gradient is computed analytically, false
503  * otherwise.
504  *
505  * Signals if the parameter gradient is computed analytically. This property
506  * is used in the function optimization process to identify parameters for
507  * which gradients need to be computed numerically.
508  ***************************************************************************/
509 inline
510 bool GOptimizerPar::has_grad(void) const
511 {
512  return m_has_grad;
513 }
514 
515 
516 /***********************************************************************//**
517  * @brief Free a parameter
518  *
519  * Frees a parameter for optimization. The parameter shall be fitted in a
520  * parameter optimization process.
521  ***************************************************************************/
522 inline
524 {
525  m_free = true;
526  return;
527 }
528 
529 
530 /***********************************************************************//**
531  * @brief Fix a parameter
532  *
533  * Fixes a parameter for optimization. The parameter shall NOT be altered
534  * in a parameter optimization process.
535  ***************************************************************************/
536 inline
538 {
539  m_free = false;
540  return;
541 }
542 
543 
544 /***********************************************************************//**
545  * @brief Set gradient property
546  *
547  * @param[in] grad Gradient flag
548  *
549  * Sets the gradient property of the parameter. If @p grad is set to
550  * true, the parameter gradient will be computed analytically by the method
551  * that evaluates the function. If false, the gradients needs to be computed
552  * numerically.
553  ***************************************************************************/
554 inline
555 void GOptimizerPar::has_grad(const bool& grad)
556 {
557  m_has_grad = grad;
558  return;
559 }
560 
561 
562 /***********************************************************************//**
563  * @brief Return parameter name
564  *
565  * @return Parameter name.
566  *
567  * Returns the parameter name.
568  ***************************************************************************/
569 inline
570 const std::string& GOptimizerPar::name(void) const
571 {
572  return m_name;
573 }
574 
575 
576 /***********************************************************************//**
577  * @brief Return parameter unit
578  *
579  * @return Parameter unit.
580  *
581  * Returns the parameter unit.
582  ***************************************************************************/
583 inline
584 const std::string& GOptimizerPar::unit(void) const
585 {
586  return m_unit;
587 }
588 
589 
590 /***********************************************************************//**
591  * @brief Set parameter name
592  *
593  * @param[in] name Parameter name.
594  *
595  * Sets the parameter name.
596  ***************************************************************************/
597 inline
598 void GOptimizerPar::name(const std::string& name)
599 {
600  m_name = name;
601  return;
602 }
603 
604 
605 /***********************************************************************//**
606  * @brief Set parameter unit
607  *
608  * @param[in] unit Parameter unit.
609  *
610  * Sets the parameter unit.
611  ***************************************************************************/
612 inline
613 void GOptimizerPar::unit(const std::string& unit)
614 {
615  m_unit = unit;
616  return;
617 }
618 
619 #endif /* GOPTIMIZERPAR_HPP */
const double & factor_error(void) const
Return parameter error factor.
void remove_min(void)
Removes minimum boundary.
GOptimizerPar * clone(void) const
Clone parameter.
bool has_range(void) const
Signal if parameter has minimum and maximum boundaries.
const double & factor_gradient(void) const
Return parameter gradient factor.
const std::string & name(void) const
Return parameter name.
XML element node class interface definition.
double gradient(void) const
Return parameter gradient.
GVector abs(const GVector &vector)
Computes absolute of vector elements.
Definition: GVector.cpp:1163
bool m_free
Parameter is free.
void factor_range(const double &min, const double &max)
Set parameter minimum and maximum factors.
GOptimizerPar(void)
Void constructor.
Definition of interface for all GammaLib classes.
double max(void) const
Return parameter maximum boundary.
double m_factor_min
Parameter minimum factor.
bool m_has_grad
Parameter has analytic gradient.
std::string m_unit
Parameter unit.
double min(void) const
Return parameter minimum boundary.
bool is_free(void) const
Signal if parameter is free.
const double & scale(void) const
Return parameter scale.
bool has_grad(void) const
Signal if parameter gradient is computed analytically.
double m_scale
Parameter scaling (true = factor * scale)
const double & factor_max(void) const
Return parameter maximum boundary factor.
void free(void)
Free a parameter.
Interface class for all GammaLib classes.
Definition: GBase.hpp:52
void fix(void)
Fix a parameter.
void autoscale(void)
Autoscale parameter.
GOptimizerPar & operator=(const GOptimizerPar &par)
Assignment operator.
bool m_has_min
Parameter has minimum boundary.
double m_factor_value
Parameter value factor.
void clear(void)
Clear parameter.
void remove_max(void)
Removes maximum boundary.
double m_factor_error
Uncertainty in parameter value factor.
bool is_fixed(void) const
Signal if parameter is fixed.
void remove_range(void)
Removes minimum and maximum boundary.
GChatter
Definition: GTypemaps.hpp:33
std::string m_name
Parameter name.
double m_factor_max
Parameter maximum factor.
bool m_has_max
Parameter has maximum boundary.
bool has_max(void) const
Signal if parameter has maximum boundary.
std::string classname(void) const
Return class name.
void free_members(void)
Delete class members.
const double & factor_min(void) const
Return parameter minimum boundary factor.
void init_members(void)
Initialise class members.
void range(const double &min, const double &max)
Set minimum and maximum parameter boundaries.
double value(void) const
Return parameter value.
bool has_min(void) const
Signal if parameter has minimum boundary.
const std::string & unit(void) const
Return parameter unit.
double error(void) const
Return parameter error.
double m_factor_gradient
Function gradient factor.
void copy_members(const GOptimizerPar &par)
Copy class members.
std::string print(const GChatter &chatter=NORMAL) const
Print parameter information.
const double & factor_value(void) const
Return parameter value factor.
virtual ~GOptimizerPar(void)
Destructor.
Optimizer parameter class.