GammaLib  2.0.0
 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-2020 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 can take
51  * - @p max gives the maximum value that the parameter 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 for m_scale > 0
83  * m_factor_max * m_scale otherwise
84  * max = m_factor_max * m_scale for m_scale > 0
85  * m_factor_min * m_scale otherwise
86  *
87  * The @p factor and @p scale terms can be set and retrieved using the
88  * factor_value(), factor_error(), factor_gradient(), factor_min(),
89  * factor_max() and scale() methods.
90  ***************************************************************************/
91 class GOptimizerPar : public GBase {
92 
93 public:
94  // Constructors and destructors
95  GOptimizerPar(void);
96  GOptimizerPar(const std::string& name, const double& value);
97  GOptimizerPar(const std::string& name, const double& factor,
98  const double& scale);
99  GOptimizerPar(const GOptimizerPar& par);
100  virtual ~GOptimizerPar(void);
101 
102  // Operators
104 
105  // Attribute methods
106  double value(void) const;
107  double error(void) const;
108  double gradient(void) const;
109  double min(void) const;
110  double max(void) const;
111  void value(const double& value);
112  void error(const double& error);
113  void gradient(const double& gradient);
114  void min(const double& min);
115  void max(const double& max);
116  void range(const double& min, const double& max);
117 
118  // Factorization methods
119  const double& factor_value(void) const;
120  const double& factor_error(void) const;
121  const double& factor_gradient(void) const;
122  const double& factor_min(void) const;
123  const double& factor_max(void) const;
124  const double& scale(void) const;
125  void factor_value(const double& value);
126  void factor_error(const double& error);
127  void factor_gradient(const double& gradient) const;
128  void factor_min(const double& min);
129  void factor_max(const double& max);
130  void factor_range(const double& min, const double& max);
131  void scale(const double& scale);
132 
133  // Boundary methods
134  bool has_min(void) const;
135  bool has_max(void) const;
136  bool has_factor_min(void) const;
137  bool has_factor_max(void) const;
138  bool has_range(void) const;
139  void remove_min(void);
140  void remove_max(void);
141  void remove_factor_min(void);
142  void remove_factor_max(void);
143  void remove_range(void);
144 
145  // Property methods
146  bool is_free(void) const;
147  bool is_fixed(void) const;
148  bool has_grad(void) const;
149  void free(void);
150  void fix(void);
151  void has_grad(const bool& grad);
152 
153  // Other methods
154  void clear(void);
155  GOptimizerPar* clone(void) const;
156  std::string classname(void) const;
157  const std::string& name(void) const;
158  const std::string& unit(void) const;
159  void name(const std::string& name);
160  void unit(const std::string& unit);
161  void autoscale(void);
162  std::string print(const GChatter& chatter = NORMAL) const;
163 
164 protected:
165  // Protected methods
166  void init_members(void);
167  void copy_members(const GOptimizerPar& par);
168  void free_members(void);
169 
170  // Proteced data members
171  std::string m_name; //!< Parameter name
172  std::string m_unit; //!< Parameter unit
173  double m_factor_value; //!< Parameter factor value
174  double m_factor_error; //!< Uncertainty in parameter factor value
175  double m_factor_min; //!< Parameter minimum factor value
176  double m_factor_max; //!< Parameter maximum factor value
177  mutable double m_factor_gradient; //!< Function factor gradient
178  double m_scale; //!< Parameter scaling (true = factor * scale)
179  bool m_free; //!< Parameter is free
180  bool m_has_factor_min; //!< Parameter has minimum factor boundary
181  bool m_has_factor_max; //!< Parameter has maximum factor boundary
182  bool m_has_grad; //!< Parameter has analytic gradient
183 };
184 
185 
186 /***********************************************************************//**
187  * @brief Return class name
188  *
189  * @return String containing the class name ("GOptimizerPar").
190  ***************************************************************************/
191 inline
192 std::string GOptimizerPar::classname(void) const
193 {
194  return ("GOptimizerPar");
195 }
196 
197 
198 /***********************************************************************//**
199  * @brief Return parameter value
200  *
201  * @return Parameter value.
202  *
203  * Returns the parameter value. The parameter value is computed by
204  * multiplying the value factor by the scale factor.
205  ***************************************************************************/
206 inline
207 double GOptimizerPar::value(void) const
208 {
209  return (m_factor_value * m_scale);
210 }
211 
212 
213 /***********************************************************************//**
214  * @brief Return parameter error
215  *
216  * @return Parameter error.
217  *
218  * Returns the parameter error. The parameter error is computed by
219  * multiplying the error factor by the scale factor. By definition, the error
220  * is a positive number, hence the method returns the absolute value of the
221  * internally computed error.
222  ***************************************************************************/
223 inline
224 double GOptimizerPar::error(void) const
225 {
226  return std::abs(m_factor_error * m_scale);
227 }
228 
229 
230 /***********************************************************************//**
231  * @brief Return parameter gradient
232  *
233  * @return Parameter gradient.
234  *
235  * Returns the parameter gradient. The parameter gradient is computed by
236  * dividing the gradient factor by the scale factor. The method returns
237  * zero in case that the scale factor is zero.
238  ***************************************************************************/
239 inline
240 double GOptimizerPar::gradient(void) const
241 {
242  // The GOptimizerPar class makes sure that m_scale is never 0, so no test
243  // is needed here
244  return (m_factor_gradient / m_scale);
245 }
246 
247 
248 /***********************************************************************//**
249  * @brief Return parameter minimum boundary
250  *
251  * @return Parameter minimum boundary.
252  *
253  * Returns the parameter minimum boundary.
254  ***************************************************************************/
255 inline
256 double GOptimizerPar::min(void) const
257 {
258  return ((m_scale < 0) ? m_factor_max * m_scale : m_factor_min * m_scale);
259 }
260 
261 
262 /***********************************************************************//**
263  * @brief Return parameter maximum boundary
264  *
265  * @return Parameter maximum boundary.
266  *
267  * Returns the parameter maximum boundary.
268  ***************************************************************************/
269 inline
270 double GOptimizerPar::max(void) const
271 {
272  return ((m_scale < 0) ? m_factor_min * m_scale : m_factor_max * m_scale);
273 }
274 
275 
276 /***********************************************************************//**
277  * @brief Return parameter factor value
278  *
279  * @return Parameter factor value.
280  *
281  * Returns the parameter factor value.
282  ***************************************************************************/
283 inline
284 const double& GOptimizerPar::factor_value(void) const
285 {
286  return (m_factor_value);
287 }
288 
289 
290 /***********************************************************************//**
291  * @brief Return parameter factor error
292  *
293  * @return Parameter factor error.
294  *
295  * Returns the parameter factor error.
296  ***************************************************************************/
297 inline
298 const double& GOptimizerPar::factor_error(void) const
299 {
300  return (m_factor_error);
301 }
302 
303 
304 /***********************************************************************//**
305  * @brief Return parameter factor gradient
306  *
307  * @return Parameter factor gradient.
308  *
309  * Returns the parameter factor gradient.
310  ***************************************************************************/
311 inline
312 const double& GOptimizerPar::factor_gradient(void) const
313 {
314  return (m_factor_gradient);
315 }
316 
317 
318 /***********************************************************************//**
319  * @brief Return parameter minimum factor boundary
320  *
321  * @return Minimum parameter factor boundary.
322  *
323  * Returns the minimum parameter factor boundary.
324  ***************************************************************************/
325 inline
326 const double& GOptimizerPar::factor_min(void) const
327 {
328  return (m_factor_min);
329 }
330 
331 
332 /***********************************************************************//**
333  * @brief Return parameter maximum factor boundary
334  *
335  * @return Maximum parameter factor boundary.
336  *
337  * Returns the maximum parameter factor boundary.
338  ***************************************************************************/
339 inline
340 const double& GOptimizerPar::factor_max(void) const
341 {
342  return (m_factor_max);
343 }
344 
345 
346 /***********************************************************************//**
347  * @brief Set minimum and maximum parameter boundaries
348  *
349  * @param[in] min Parameter minimum.
350  * @param[in] max Parameter maximum.
351  *
352  * Sets the minimum and maximum parameter boundaries.
353  ***************************************************************************/
354 inline
355 void GOptimizerPar::range(const double& min, const double& max)
356 {
357  this->min(min);
358  this->max(max);
359  return;
360 }
361 
362 
363 /***********************************************************************//**
364  * @brief Return parameter scale
365  *
366  * @return Parameter scale factor.
367  *
368  * Returns the parameter scale factor.
369  ***************************************************************************/
370 inline
371 const double& GOptimizerPar::scale(void) const
372 {
373  return (m_scale);
374 }
375 
376 
377 /***********************************************************************//**
378  * @brief Set parameter factor error
379  *
380  * @param[in] error Parameter factor error.
381  *
382  * Sets the parameter factor error.
383  ***************************************************************************/
384 inline
385 void GOptimizerPar::factor_error(const double& error)
386 {
388  return;
389 }
390 
391 
392 /***********************************************************************//**
393  * @brief Set parameter factor gradient
394  *
395  * @param[in] gradient Parameter factor gradient.
396  *
397  * Sets the parameter factor gradient.
398  ***************************************************************************/
399 inline
400 void GOptimizerPar::factor_gradient(const double& gradient) const
401 {
403  return;
404 }
405 
406 
407 /***********************************************************************//**
408  * @brief Signal if parameter has minimum boundary
409  *
410  * @return True if parameter has minimum boundary, false otherwise.
411  *
412  * Signals if the parameter has a minimum boundary.
413  ***************************************************************************/
414 inline
415 bool GOptimizerPar::has_min(void) const
416 {
417  return ((m_scale < 0) ? m_has_factor_max : m_has_factor_min);
418 }
419 
420 
421 /***********************************************************************//**
422  * @brief Signal if parameter has maximum boundary
423  *
424  * @return True if parameter has maximum boundary, false otherwise.
425  *
426  * Signals if the parameter has a maximum boundary.
427  ***************************************************************************/
428 inline
429 bool GOptimizerPar::has_max(void) const
430 {
431  return ((m_scale < 0) ? m_has_factor_min : m_has_factor_max);
432 }
433 
434 
435 /***********************************************************************//**
436  * @brief Signal if parameter has minimum factor boundary
437  *
438  * @return True if parameter has minimum factor boundary, false otherwise.
439  *
440  * Signals if the parameter has a minimum factor boundary.
441  ***************************************************************************/
442 inline
444 {
445  return m_has_factor_min;
446 }
447 
448 
449 /***********************************************************************//**
450  * @brief Signal if parameter has maximum factor boundary
451  *
452  * @return True if parameter has maximum factor boundary, false otherwise.
453  *
454  * Signals if the parameter has a maximum factor boundary.
455  ***************************************************************************/
456 inline
458 {
459  return m_has_factor_max;
460 }
461 
462 
463 /***********************************************************************//**
464  * @brief Signal if parameter has minimum and maximum boundaries
465  *
466  * @return True if parameter has minimum and maximum boundaries, false
467  * otherwise.
468  *
469  * Signals if the parameter has a minimum and a maximum boundary.
470  ***************************************************************************/
471 inline
472 bool GOptimizerPar::has_range(void) const
473 {
475 }
476 
477 
478 /***********************************************************************//**
479  * @brief Removes minimum boundary
480  *
481  * Removes minimum boundary from the parameter.
482  ***************************************************************************/
483 inline
485 {
486  if (m_scale < 0) {
487  m_has_factor_max = false;
488  m_factor_max = 0.0;
489  }
490  else {
491  m_has_factor_min = false;
492  m_factor_min = 0.0;
493  }
494  return;
495 }
496 
497 
498 /***********************************************************************//**
499  * @brief Removes maximum boundary
500  *
501  * Removes maximum boundary from the parameter.
502  ***************************************************************************/
503 inline
505 {
506  if (m_scale < 0) {
507  m_has_factor_min = false;
508  m_factor_min = 0.0;
509  }
510  else {
511  m_has_factor_max = false;
512  m_factor_max = 0.0;
513  }
514  return;
515 }
516 
517 
518 /***********************************************************************//**
519  * @brief Removes minimum factor boundary
520  *
521  * Removes minimum factor boundary from the parameter.
522  ***************************************************************************/
523 inline
525 {
526  m_has_factor_min = false;
527  m_factor_min = 0.0;
528  return;
529 }
530 
531 
532 /***********************************************************************//**
533  * @brief Removes maximum factor boundary
534  *
535  * Removes maximum factor boundary from the parameter.
536  ***************************************************************************/
537 inline
539 {
540  m_has_factor_max = false;
541  m_factor_max = 0.0;
542  return;
543 }
544 
545 
546 /***********************************************************************//**
547  * @brief Removes minimum and maximum boundary
548  *
549  * Removes minimum and maximum boundary from the parameter.
550  ***************************************************************************/
551 inline
553 {
554  m_has_factor_min = false;
555  m_has_factor_max = false;
556  return;
557 }
558 
559 
560 /***********************************************************************//**
561  * @brief Signal if parameter is free
562  *
563  * @return True if parameter is free, false otherwise.
564  *
565  * Signals if the parameter is free, i.e. that it shall be fitted in a
566  * parameter optimization process.
567  ***************************************************************************/
568 inline
569 bool GOptimizerPar::is_free(void) const
570 {
571  return m_free;
572 }
573 
574 
575 /***********************************************************************//**
576  * @brief Signal if parameter is fixed
577  *
578  * @return True if parameter is fixed, false otherwise.
579  *
580  * Signals if the parameter is fixed, i.e. that it shall NOT be fitted in a
581  * parameter optimization process.
582  ***************************************************************************/
583 inline
584 bool GOptimizerPar::is_fixed(void) const
585 {
586  return (!m_free);
587 }
588 
589 
590 /***********************************************************************//**
591  * @brief Signal if parameter gradient is computed analytically
592  *
593  * @return True if parameter is gradient is computed analytically, false
594  * otherwise.
595  *
596  * Signals if the parameter gradient is computed analytically. This property
597  * is used in the function optimization process to identify parameters for
598  * which gradients need to be computed numerically.
599  ***************************************************************************/
600 inline
601 bool GOptimizerPar::has_grad(void) const
602 {
603  return m_has_grad;
604 }
605 
606 
607 /***********************************************************************//**
608  * @brief Free a parameter
609  *
610  * Frees a parameter for optimization. The parameter shall be fitted in a
611  * parameter optimization process.
612  ***************************************************************************/
613 inline
615 {
616  m_free = true;
617  return;
618 }
619 
620 
621 /***********************************************************************//**
622  * @brief Fix a parameter
623  *
624  * Fixes a parameter for optimization. The parameter shall NOT be altered
625  * in a parameter optimization process.
626  ***************************************************************************/
627 inline
629 {
630  m_free = false;
631  return;
632 }
633 
634 
635 /***********************************************************************//**
636  * @brief Set gradient property
637  *
638  * @param[in] grad Gradient flag
639  *
640  * Sets the gradient property of the parameter. If @p grad is set to
641  * true, the parameter gradient will be computed analytically by the method
642  * that evaluates the function. If false, the gradients needs to be computed
643  * numerically.
644  ***************************************************************************/
645 inline
646 void GOptimizerPar::has_grad(const bool& grad)
647 {
648  m_has_grad = grad;
649  return;
650 }
651 
652 
653 /***********************************************************************//**
654  * @brief Return parameter name
655  *
656  * @return Parameter name.
657  *
658  * Returns the parameter name.
659  ***************************************************************************/
660 inline
661 const std::string& GOptimizerPar::name(void) const
662 {
663  return m_name;
664 }
665 
666 
667 /***********************************************************************//**
668  * @brief Return parameter unit
669  *
670  * @return Parameter unit.
671  *
672  * Returns the parameter unit.
673  ***************************************************************************/
674 inline
675 const std::string& GOptimizerPar::unit(void) const
676 {
677  return m_unit;
678 }
679 
680 
681 /***********************************************************************//**
682  * @brief Set parameter name
683  *
684  * @param[in] name Parameter name.
685  *
686  * Sets the parameter name.
687  ***************************************************************************/
688 inline
689 void GOptimizerPar::name(const std::string& name)
690 {
691  m_name = name;
692  return;
693 }
694 
695 
696 /***********************************************************************//**
697  * @brief Set parameter unit
698  *
699  * @param[in] unit Parameter unit.
700  *
701  * Sets the parameter unit.
702  ***************************************************************************/
703 inline
704 void GOptimizerPar::unit(const std::string& unit)
705 {
706  m_unit = unit;
707  return;
708 }
709 
710 #endif /* GOPTIMIZERPAR_HPP */
const double & factor_error(void) const
Return parameter factor error.
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 factor gradient.
bool has_factor_max(void) const
Signal if parameter has maximum factor boundary.
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:1253
bool m_free
Parameter is free.
void factor_range(const double &min, const double &max)
Set minimum and maximum parameter boundary factors.
GOptimizerPar(void)
Void constructor.
bool has_factor_min(void) const
Signal if parameter has minimum factor boundary.
Definition of interface for all GammaLib classes.
double max(void) const
Return parameter maximum boundary.
double m_factor_min
Parameter minimum factor value.
bool m_has_grad
Parameter has analytic gradient.
double min(const GVector &vector)
Computes minimum vector element.
Definition: GVector.cpp:886
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 factor boundary.
void free(void)
Free a parameter.
void remove_factor_max(void)
Removes maximum factor boundary.
void remove_factor_min(void)
Removes minimum factor boundary.
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.
double m_factor_value
Parameter factor value.
void clear(void)
Clear parameter.
void remove_max(void)
Removes maximum boundary.
double m_factor_error
Uncertainty in parameter factor value.
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 value.
bool has_max(void) const
Signal if parameter has maximum boundary.
std::string classname(void) const
Return class name.
double max(const GVector &vector)
Computes maximum vector element.
Definition: GVector.cpp:915
void free_members(void)
Delete class members.
const double & factor_min(void) const
Return parameter minimum factor boundary.
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.
bool m_has_factor_max
Parameter has maximum factor boundary.
double error(void) const
Return parameter error.
double m_factor_gradient
Function factor gradient.
void copy_members(const GOptimizerPar &par)
Copy class members.
bool m_has_factor_min
Parameter has minimum factor boundary.
std::string print(const GChatter &chatter=NORMAL) const
Print parameter information.
const double & factor_value(void) const
Return parameter factor value.
virtual ~GOptimizerPar(void)
Destructor.
Optimizer parameter class.