GammaLib  2.1.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GModel.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GModel.hpp - Abstract virtual model base class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2009-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 GModel.hpp
23  * @brief Abstract model base class interface definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GMODEL_HPP
28 #define GMODEL_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <vector>
32 #include <string>
33 #include "GBase.hpp"
34 #include "GModelPar.hpp"
35 #include "GModelAssociations.hpp"
36 #include "GXmlElement.hpp"
37 #include "GEnergy.hpp"
38 #include "GTime.hpp"
39 
40 /* __ Forward declarations _______________________________________________ */
41 class GVector;
42 class GMatrixSparse;
43 class GEvent;
44 class GObservation;
45 
46 
47 /***********************************************************************//**
48  * @class GModel
49  *
50  * @brief Abstract model class
51  *
52  * This class implements a parametric model. The eval() method evaluates the
53  * model for a given event and observation. If the gradients parameter is set
54  * to true, the eval() method also computes analytical parameter gradients if
55  * they exist.
56  *
57  * A model has the following attributes:
58  * - @p name
59  * - @p type
60  * - @p instruments
61  * - @p ids
62  * - @p scales
63  *
64  * The model @p name is a text string that names the model. The name()
65  * methods allow setting and retrieving the model name. The model handling
66  * does not actual depend on the value of this text string.
67  *
68  * The model @p type is a text string that specifies the kind of the model.
69  * Examples are @p PointSource, @p ExtendedSource or @p DiffuseSource for
70  * sky models. The type() method allows retrieving the model type. The model
71  * handling does not actual depend on the value of this text string.
72  *
73  * The model @p instruments is a list of text strings that specifies the
74  * instruments to which the model applies. The is_valid() method will check
75  * a given instrument name against that list to verify if the model applies
76  * to an instrument. The instruments() method returns a comma separated
77  * list of all instruments. Another instance of this method allows setting
78  * the instrument list from a comma separated list. If the @p instruments
79  * list is empty, the model applies to all instruments.
80  *
81  * The model @p ids is a list of text strings that specifies the observation
82  * identifiers to which the model applies. This allows specifying of models
83  * for a specific list of observations. The is_valid() method will check
84  * a given observation identifier against that list to verify if the model
85  * applies. The ids() method returns a comma separated list of all
86  * observation identifiers. Another instance of this method allows setting
87  * the observation identifiers from a comma separated list. If the @p ids
88  * list is empty, the model applies to all observation identifiers.
89  *
90  * The model @p scales is a list of model parameters that specify an
91  * instrument dependent scaling factor. This allows to prescale a model for
92  * a given instrument. The scale() methods allow to set and to retrieve the
93  * scale factor for a specific instrument.
94  *
95  * As the class holds simply a collection of model parameters, it should
96  * neither deal with allocation and deallocation, nor with cloning of
97  * model parameters. This will be done by the classes that actually
98  * implement the model parameters.
99  ***************************************************************************/
100 class GModel : public GBase {
101 
102 public:
103  // Constructors and destructors
104  GModel(void);
105  explicit GModel(const GXmlElement& xml);
106  GModel(const GModel& model);
107  virtual ~GModel(void);
108 
109  // Operators
110  virtual GModel& operator=(const GModel& model);
111  virtual GModelPar& operator[](const int& index);
112  virtual const GModelPar& operator[](const int& index) const;
113  virtual GModelPar& operator[](const std::string& name);
114  virtual const GModelPar& operator[](const std::string& name) const;
115 
116  // Pure virtual methods
117  virtual void clear(void) = 0;
118  virtual GModel* clone(void) const = 0;
119  virtual std::string classname(void) const = 0;
120  virtual std::string type(void) const = 0;
121  virtual bool is_constant(void) const = 0;
122  virtual double eval(const GEvent& event,
123  const GObservation& obs,
124  const bool& gradients = false) const = 0;
125  virtual GVector eval(const GObservation& obs,
126  GMatrixSparse* gradients = NULL) const = 0;
127  virtual double npred(const GEnergy& obsEng, const GTime& obsTime,
128  const GObservation& obs) const = 0;
129  virtual void read(const GXmlElement& xml) = 0;
130  virtual void write(GXmlElement& xml) const = 0;
131  virtual std::string print(const GChatter& chatter = NORMAL) const = 0;
132 
133  // Implemented methods
134  int size(void) const;
135  int scales(void) const;
136  GModelPar& at(const int& index);
137  const GModelPar& at(const int& index) const;
138  bool has_par(const std::string& name) const;
139  bool has_scales(void) const;
140  const std::string& name(void) const;
141  void name(const std::string& name);
142  const double& ts(void) const;
143  void ts(const double& ts);
144  const bool& tscalc(void) const;
145  void tscalc(const bool& tscalc);
146  const bool& has_ts(void) const;
147  std::string instruments(void) const;
148  void instruments(const std::string& instruments);
149  GModelPar& scale(const int& index);
150  const GModelPar& scale(const int& index) const;
151  GModelPar scale(const std::string& instrument) const;
152  void scale(const GModelPar& par);
153  std::string ids(void) const;
154  void ids(const std::string& ids);
155  bool is_valid(const std::string& instruments,
156  const std::string& ids) const;
157  const GModelAssociations& associations(void) const;
158  void associations(const GModelAssociations& associations);
159  const bool& has_eval_indices(void) const;
160  const std::vector<int>& eval_indices(void) const;
161 
162 protected:
163  // Protected methods
164  void init_members(void);
165  void copy_members(const GModel& model);
166  void free_members(void);
167  void read_attributes(const GXmlElement& xml);
168  void write_attributes(GXmlElement& xml) const;
169  std::string print_attributes(void) const;
170  void read_scales(const GXmlElement& xml);
171  void write_scales(GXmlElement& xml) const;
172 
173  // Protected members
174  std::string m_name; //!< Model name
175  std::vector<std::string> m_instruments; //!< Instruments to which model applies
176  std::vector<GModelPar> m_scales; //!< Model instrument scale factors
177  std::vector<std::string> m_ids; //!< Identifiers to which model applies
178  std::vector<GModelPar*> m_pars; //!< Pointers to all model parameters
179  GModelAssociations m_associations; //!< Model associations
180  bool m_has_ts; //!< Signals if TS is available
181  bool m_has_tscalc; //!< Signals if tscalc attribute is available
182  bool m_tscalc; //!< Signals if TS should be computed
183  double m_ts; //!< Test Statistic of the model
184 
185  // Protected members for efficient gradient access
186  mutable bool m_has_eval_inx; //!< Signal that parameter indices
187  //!< updated by eval() method exist
188  mutable std::vector<int> m_eval_inx; //!< List of parameter indices updated
189  //!< by eval() method
190 };
191 
192 
193 /***********************************************************************//**
194  * @brief Returns reference to model parameter by index
195  *
196  * @param[in] index Parameter index [0,...,size()-1].
197  * @return Reference to model parameter.
198  *
199  * Returns a reference to the model parameter of the specified @p index.
200  ***************************************************************************/
201 inline
202 GModelPar& GModel::operator[](const int& index)
203 {
204  // Return reference
205  return *(m_pars[index]);
206 }
207 
208 
209 /***********************************************************************//**
210  * @brief Returns reference to model parameter by index (const version)
211  *
212  * @param[in] index Parameter index [0,...,size()-1].
213  * @return Const reference to model parameter.
214  *
215  * Returns a const reference to the model parameter of the specified
216  ***************************************************************************/
217 inline
218 const GModelPar& GModel::operator[](const int& index) const
219 {
220  // Return reference
221  return *(m_pars[index]);
222 }
223 
224 
225 /***********************************************************************//**
226  * @brief Return number of parameters in model
227  *
228  * @return Number of parameters in model.
229  *
230  * Returns the number of parameters in the model.
231  ***************************************************************************/
232 inline
233 int GModel::size(void) const
234 {
235  return (int)m_pars.size();
236 }
237 
238 
239 /***********************************************************************//**
240  * @brief Return number of scale parameters in model
241  *
242  * @return Number of scale parameters in model.
243  *
244  * Returns the number of scale parameters in the model.
245  ***************************************************************************/
246 inline
247 int GModel::scales(void) const
248 {
249  return (int)m_scales.size();
250 }
251 
252 
253 /***********************************************************************//**
254  * @brief Return parameter name
255  *
256  * @return Parameter name.
257  *
258  * Returns the parameter name.
259  ***************************************************************************/
260 inline
261 const std::string& GModel::name(void) const
262 {
263  return m_name;
264 }
265 
266 
267 /***********************************************************************//**
268  * @brief Set parameter name
269  *
270  * @param[in] name Parameter name.
271  *
272  * Set the parameter name.
273  ***************************************************************************/
274 inline
275 void GModel::name(const std::string& name)
276 {
277  m_name = name;
278  return;
279 }
280 
281 
282 /***********************************************************************//**
283  * @brief Return Test Statistic value
284  *
285  * @return Test Statistic value.
286  *
287  * Returns the Test Statistic value. The Test Statistic value is twice the
288  * difference between the log-likelihood of the null hypothesis and the
289  * alternative hypothesis.
290  ***************************************************************************/
291 inline
292 const double& GModel::ts(void) const
293 {
294  return m_ts;
295 }
296 
297 
298 /***********************************************************************//**
299  * @brief Set Test Statistic value
300  *
301  * @param[in] ts Test Statistic value.
302  *
303  * Set the Test Statistic value. The Test Statistic value is twice the
304  * difference between the log-likelihood of the null hypothesis and the
305  * alternative hypothesis.
306  ***************************************************************************/
307 inline
308 void GModel::ts(const double& ts)
309 {
310  m_ts = ts;
311  m_has_ts = true; //!< Signals that TS is now available
312  return;
313 }
314 
315 
316 /***********************************************************************//**
317  * @brief Return Test Statistic computation flag
318  *
319  * @return Test Statistic computation flag; true is Test Statistic should be
320  * computed.
321  *
322  * Returns the flag that signals whether Test Statistic values should be
323  * computed.
324  ***************************************************************************/
325 inline
326 const bool& GModel::tscalc(void) const
327 {
328  return m_tscalc;
329 }
330 
331 
332 /***********************************************************************//**
333  * @brief Set Test Statistic computation flag
334  *
335  * @param[in] tscalc Test Statistic computation flag.
336  *
337  * Set the flag that signals whether Test Statistic values should be
338  * computed.
339  ***************************************************************************/
340 inline
341 void GModel::tscalc(const bool& tscalc)
342 {
343  m_tscalc = tscalc;
344  m_has_tscalc = true; //!< Signals that tscalc is now available
345  return;
346 }
347 
348 
349 /***********************************************************************//**
350  * @brief Signals that model has scales
351  *
352  * @return True if model has scale factors.
353  ***************************************************************************/
354 inline
355 bool GModel::has_scales(void) const
356 {
357  return (!m_scales.empty());
358 }
359 
360 
361 /***********************************************************************//**
362  * @brief Signals that model has Test Statistics value
363  *
364  * @return True if model has TS value.
365  ***************************************************************************/
366 inline
367 const bool& GModel::has_ts(void) const
368 {
369  return m_has_ts;
370 }
371 
372 
373 /***********************************************************************//**
374  * @brief Return model associations
375  *
376  * @return Model associations.
377  *
378  * Returns model associations.
379  ***************************************************************************/
380 inline
382 {
383  return m_associations;
384 }
385 
386 
387 /***********************************************************************//**
388  * @brief Set model associations
389  *
390  * @param[in] associations Model associations.
391  *
392  * Set the model associations.
393  ***************************************************************************/
394 inline
395 void GModel::associations(const GModelAssociations& associations)
396 {
398  return;
399 }
400 
401 
402 /***********************************************************************//**
403  * @brief Signals that parameter indices updated by eval() method were set
404  *
405  * @return True if parameter indices updated by eval() method were set.
406  ***************************************************************************/
407 inline
408 const bool& GModel::has_eval_indices(void) const
409 {
410  return m_has_eval_inx;
411 }
412 
413 
414 /***********************************************************************//**
415  * @brief Return vector of parameter indices updated by eval() method
416  *
417  * @return Vector of parameter indices updated by eval() method.
418  ***************************************************************************/
419 inline
420 const std::vector<int>& GModel::eval_indices(void) const
421 {
422  return m_eval_inx;
423 }
424 
425 #endif /* GMODEL_HPP */
virtual ~GModel(void)
Destructor.
Definition: GModel.cpp:110
Abstract model class.
Definition: GModel.hpp:100
void free_members(void)
Delete class members.
Definition: GModel.cpp:672
int scales(void) const
Return number of scale parameters in model.
Definition: GModel.hpp:247
virtual bool is_constant(void) const =0
virtual void write(GXmlElement &xml) const =0
Energy value class definition.
std::string print_attributes(void) const
Print model attributes.
Definition: GModel.cpp:770
Sparse matrix class interface definition.
XML element node class interface definition.
double m_ts
Test Statistic of the model.
Definition: GModel.hpp:183
virtual double eval(const GEvent &event, const GObservation &obs, const bool &gradients=false) const =0
Abstract interface for the event classes.
Definition: GEvent.hpp:71
Definition of interface for all GammaLib classes.
XML element node class.
Definition: GXmlElement.hpp:48
const bool & has_eval_indices(void) const
Signals that parameter indices updated by eval() method were set.
Definition: GModel.hpp:408
GModelAssociations m_associations
Model associations.
Definition: GModel.hpp:179
virtual std::string classname(void) const =0
Return class name.
bool m_has_eval_inx
Definition: GModel.hpp:186
Time class.
Definition: GTime.hpp:55
std::string ids(void) const
Returns observation identifiers to which model applies.
Definition: GModel.cpp:502
const std::vector< int > & eval_indices(void) const
Return vector of parameter indices updated by eval() method.
Definition: GModel.hpp:420
Model associations container class definition.
bool m_tscalc
Signals if TS should be computed.
Definition: GModel.hpp:182
bool has_par(const std::string &name) const
Checks if parameter name exists.
Definition: GModel.cpp:284
bool m_has_ts
Signals if TS is available.
Definition: GModel.hpp:180
std::vector< GModelPar > m_scales
Model instrument scale factors.
Definition: GModel.hpp:176
bool m_has_tscalc
Signals if tscalc attribute is available.
Definition: GModel.hpp:181
std::vector< GModelPar * > m_pars
Pointers to all model parameters.
Definition: GModel.hpp:178
Model parameter class interface definition.
int size(void) const
Return number of parameters in model.
Definition: GModel.hpp:233
void init_members(void)
Initialise class members.
Definition: GModel.cpp:622
bool is_valid(const std::string &instruments, const std::string &ids) const
Verifies if model is valid for a given instrument and identifier.
Definition: GModel.cpp:570
Model parameter class.
Definition: GModelPar.hpp:87
virtual void read(const GXmlElement &xml)=0
std::vector< std::string > m_instruments
Instruments to which model applies.
Definition: GModel.hpp:175
void copy_members(const GModel &model)
Copy class members.
Definition: GModel.cpp:648
GModelPar & at(const int &index)
Returns reference to model parameter by index.
Definition: GModel.cpp:239
virtual GModelPar & operator[](const int &index)
Returns reference to model parameter by index.
Definition: GModel.hpp:202
const bool & has_ts(void) const
Signals that model has Test Statistics value.
Definition: GModel.hpp:367
const std::string & name(void) const
Return parameter name.
Definition: GModel.hpp:261
Interface class for all GammaLib classes.
Definition: GBase.hpp:52
virtual void clear(void)=0
Clear object.
std::vector< std::string > m_ids
Identifiers to which model applies.
Definition: GModel.hpp:177
virtual double npred(const GEnergy &obsEng, const GTime &obsTime, const GObservation &obs) const =0
std::string instruments(void) const
Returns instruments to which model applies.
Definition: GModel.cpp:310
GChatter
Definition: GTypemaps.hpp:33
const double & ts(void) const
Return Test Statistic value.
Definition: GModel.hpp:292
Abstract observation base class.
bool has_scales(void) const
Signals that model has scales.
Definition: GModel.hpp:355
GModelPar & scale(const int &index)
Returns reference to scale parameter by index.
Definition: GModel.cpp:369
void write_attributes(GXmlElement &xml) const
Write model attributes.
Definition: GModel.cpp:723
virtual GModel * clone(void) const =0
Clones object.
std::string m_name
Model name.
Definition: GModel.hpp:174
GModel(void)
Void constructor.
Definition: GModel.cpp:57
virtual std::string print(const GChatter &chatter=NORMAL) const =0
Print content of object.
virtual std::string type(void) const =0
const GModelAssociations & associations(void) const
Return model associations.
Definition: GModel.hpp:381
std::vector< int > m_eval_inx
Definition: GModel.hpp:188
void read_scales(const GXmlElement &xml)
Read instrument scales from XML element.
Definition: GModel.cpp:849
void read_attributes(const GXmlElement &xml)
Read model attributes.
Definition: GModel.cpp:684
Model associations container class.
virtual GModel & operator=(const GModel &model)
Assignment operator.
Definition: GModel.cpp:132
Vector class.
Definition: GVector.hpp:46
void write_scales(GXmlElement &xml) const
Write instrument scales into XML element.
Definition: GModel.cpp:897
const bool & tscalc(void) const
Return Test Statistic computation flag.
Definition: GModel.hpp:326
Time class interface definition.
Class that handles energies in a unit independent way.
Definition: GEnergy.hpp:48