GammaLib  1.7.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GModels.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GModels.hpp - Model container class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2009-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 GModels.hpp
23  * @brief Model container class definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GMODELS_HPP
28 #define GMODELS_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <string>
32 #include "GContainer.hpp"
33 #include "GModel.hpp"
34 #include "GOptimizerPars.hpp"
35 #include "GXml.hpp"
36 
37 /* __ Forward declarations _______________________________________________ */
38 class GEvent;
39 class GObservation;
40 class GFilename;
41 
42 
43 /***********************************************************************//**
44  * @class GModels
45  *
46  * @brief Model container class
47  *
48  * This container class collects models of type GModel that are used to
49  * describe the data. The names of all models in the container have to be
50  * unique, i.e. every name can occur only once. This allows for accessing the
51  * models by name and by index.
52  *
53  * The GModels class provides methods to manage and to access the models
54  * in the container. The number of models in the container is retrieved
55  * using the size() method. The is_empty() method can be used to check
56  * whether the container is empty or whether it contains models:
57  *
58  * GModels models; // Allocate container
59  * int n = models.size(); // Number of models in container
60  * if (models.is_empty()) // Check for emptiness
61  * std::cout << "Empty container";
62  *
63  * Access operators exist for accessing of models by index or by name:
64  *
65  * GModel* mptr = models[i]; // Get i'th model
66  * GModel* mptr = models["Crab"]; // Get a model named "Crab"
67  *
68  * The index access operator does not check the validity of the provided
69  * index. For index validation, use the at() method:
70  *
71  * GModel* mptr = models.at(i); // Get i'th model with index check
72  *
73  * The append() method add a model to the container:
74  *
75  * models.append(model); // Append model
76  *
77  * The append() method clones the model that is passed as argument. The
78  * method returns a pointer to the cloned model so that the attributes of
79  * the cloned model can be manipulated:
80  *
81  * GModel* mptr = models.append(model);
82  *
83  * The insert() methods insert a model before a given index or before
84  * a model with a given name (the methods also return a pointer to the
85  * cloned model):
86  *
87  * models.insert(i, model); // Insert before i'th model
88  * models.insert("Crab", model); // Insert before "Crab" model
89  *
90  * The set() methods replace an existing model by index or by name (also
91  * these methods return a pointer to the cloned model):
92  *
93  * models.set(i, model); // Replace i'th model
94  * models.set("Crab", model); // Replace "Crab" model
95  *
96  * The remove() methods remove an existing model by index or by name:
97  *
98  * models.remove(i); // Remove i'th model
99  * models.remove("Crab"); // Remove "Crab" model
100  *
101  * The existence of a model with a given name can be checked using
102  *
103  * if (models.contains("Crab"))
104  * std::cout << "We have the Crab!";
105  *
106  * The extend() method extends a container by all models found in another
107  * container:
108  *
109  * models.extend(other_models); // Extend container
110  *
111  * For repeated container manipulations, a given @p number of model slots can
112  * be reserved using
113  *
114  * models.reserve(number); // Reserves model slots
115  *
116  * which will speed up the memory allocations for new models.
117  *
118  * Models can be saved into or loaded from an XML file using
119  *
120  * models.save("mymodels.xml"); // Save models in XML file
121  * models.load("mymodels.xml"); // Load models from XML file
122  *
123  * The models can also be loaded upon construction from an XML file:
124  *
125  * GModels models("mymodels.xml"); // Construct by loading models from XML file
126  *
127  * The class can also directly operate on a GXml object using the read() and
128  * write() methods:
129  *
130  * GXml xml; // Allocate GXml object
131  * models.write(xml); // Write into GXml object
132  * models.read(xml); // Read models from GXml object
133  *
134  * The sum of all models in the container are evaluated for a given @p event
135  * and @p observation using the eval() method:
136  *
137  * double value = models.eval(event, observation);
138  *
139  * If the eval() method is called with the optional gradients parameter set
140  * to true, i.e.
141  *
142  * double value = models.eval(event, observation, true);
143  *
144  * the method computes also the parameter gradients for all free model
145  * parameters that have an analytical parameter gradient.
146  *
147  * The only member of GModels is a list of model pointers. The class handles
148  * the proper allocation and deallocation of the model memory.
149  ***************************************************************************/
150 class GModels : public GContainer {
151 
152 public:
153  // Constructors and destructors
154  GModels(void);
155  GModels(const GModels& models);
156  explicit GModels(const GFilename& filename);
157  virtual ~GModels(void);
158 
159  // Operators
160  GModels& operator=(const GModels& models);
161  GModel* operator[](const int& index);
162  const GModel* operator[](const int& index) const;
163  GModel* operator[](const std::string& name);
164  const GModel* operator[](const std::string& name) const;
165 
166  // Methods
167  void clear(void);
168  GModels* clone(void) const;
169  std::string classname(void) const;
170  GModel* at(const int& index);
171  const GModel* at(const int& index) const;
172  int size(void) const;
173  bool is_empty(void) const;
174  GModel* set(const int& index, const GModel& model);
175  GModel* set(const std::string& name, const GModel& model);
176  GModel* append(const GModel& model);
177  GModel* insert(const int& index, const GModel& model);
178  GModel* insert(const std::string& name, const GModel& model);
179  void remove(const int& index);
180  void remove(const std::string& name);
181  void reserve(const int& num);
182  void extend(const GModels& models);
183  bool contains(const std::string& name) const;
184  void load(const GFilename& filename);
185  void save(const GFilename& filename) const;
186  void read(const GXml& xml);
187  void write(GXml& xml) const;
188  int npars(void) const;
189  GOptimizerPars pars(void) const;
190  double eval(const GEvent& event,
191  const GObservation& obs,
192  const bool& gradients = false) const;
193  std::string print(const GChatter& chatter = NORMAL) const;
194 
195 protected:
196  // Protected methods
197  void init_members(void);
198  void copy_members(const GModels& models);
199  void free_members(void);
200  int get_index(const std::string& name) const;
201 
202  // Proteced members
203  std::vector<GModel*> m_models; //!< List of models
204 };
205 
206 
207 /***********************************************************************//**
208  * @brief Return class name
209  *
210  * @return String containing the class name ("GModels").
211  ***************************************************************************/
212 inline
213 std::string GModels::classname(void) const
214 {
215  return ("GModels");
216 }
217 
218 
219 /***********************************************************************//**
220  * @brief Return pointer to model
221  *
222  * @param[in] index Model index [0,...,size()-1].
223  *
224  * Returns a pointer to the model with the specified @p index.
225  ***************************************************************************/
226 inline
227 GModel* GModels::operator[](const int& index)
228 {
229  return (m_models[index]);
230 }
231 
232 
233 /***********************************************************************//**
234  * @brief Return pointer to model (const version)
235  *
236  * @param[in] index Model index [0,...,size()-1].
237  *
238  * Returns a const pointer to the model with the specified @p index.
239  ***************************************************************************/
240 inline
241 const GModel* GModels::operator[](const int& index) const
242 {
243  return (m_models[index]);
244 }
245 
246 
247 /***********************************************************************//**
248  * @brief Return number of models in container
249  *
250  * @return Number of models in container.
251  *
252  * Returns the number of models in the model container.
253  ***************************************************************************/
254 inline
255 int GModels::size(void) const
256 {
257  return (int)m_models.size();
258 }
259 
260 
261 /***********************************************************************//**
262  * @brief Signals if there are no models in container
263  *
264  * @return True if container is empty, false otherwise.
265  *
266  * Signals if the model container does not contain any model.
267  ***************************************************************************/
268 inline
269 bool GModels::is_empty(void) const
270 {
271  return (m_models.empty());
272 }
273 
274 
275 /***********************************************************************//**
276  * @brief Reserves space for models in container
277  *
278  * @param[in] num Number of models
279  *
280  * Reserves space for @p num models in the container.
281  ***************************************************************************/
282 inline
283 void GModels::reserve(const int& num)
284 {
285  m_models.reserve(num);
286  return;
287 }
288 
289 #endif /* GMODELS_HPP */
double eval(const GEvent &event, const GObservation &obs, const bool &gradients=false) const
Evaluate sum of all models.
Definition: GModels.cpp:871
Abstract model class.
Definition: GModel.hpp:97
void copy_members(const GModels &models)
Copy class members.
Definition: GModels.cpp:955
Abstract model base class interface definition.
void read(const GXml &xml)
Read models from XML document.
Definition: GModels.cpp:737
XML class interface definition.
GModels * clone(void) const
Clone instance.
Definition: GModels.cpp:246
GModels(void)
Void constructor.
Definition: GModels.cpp:70
GModel * operator[](const int &index)
Return pointer to model.
Definition: GModels.hpp:227
Optimizer parameter container class.
Abstract interface for the event classes.
Definition: GEvent.hpp:71
void extend(const GModels &models)
Append model container.
Definition: GModels.cpp:605
GOptimizerPars pars(void) const
Return optimizer parameter container.
Definition: GModels.cpp:838
void save(const GFilename &filename) const
Save models into XML file.
Definition: GModels.cpp:695
void reserve(const int &num)
Reserves space for models in container.
Definition: GModels.hpp:283
GModel * insert(const int &index, const GModel &model)
Insert model into container.
Definition: GModels.cpp:450
void clear(void)
Clear object.
Definition: GModels.cpp:226
std::vector< GModel * > m_models
List of models.
Definition: GModels.hpp:203
int get_index(const std::string &name) const
Return model index by name.
Definition: GModels.cpp:996
Model container class.
Definition: GModels.hpp:150
void free_members(void)
Delete class members.
Definition: GModels.cpp:974
std::string classname(void) const
Return class name.
Definition: GModels.hpp:213
XML class.
Definition: GXml.hpp:172
Filename class.
Definition: GFilename.hpp:62
GModel * set(const int &index, const GModel &model)
Set model in container.
Definition: GModels.cpp:314
GChatter
Definition: GTypemaps.hpp:33
Optimizer parameters base class definition.
Abstract observation base class.
void write(GXml &xml) const
Write models into XML document.
Definition: GModels.cpp:788
GModel * at(const int &index)
Return pointer to model.
Definition: GModels.cpp:262
void load(const GFilename &filename)
Load models from XML file.
Definition: GModels.cpp:672
bool contains(const std::string &name) const
Signals if model name exists.
Definition: GModels.cpp:654
std::string print(const GChatter &chatter=NORMAL) const
Print models.
Definition: GModels.cpp:898
void init_members(void)
Initialise class members.
Definition: GModels.cpp:936
int npars(void) const
Return number of model parameters in container.
Definition: GModels.cpp:813
virtual ~GModels(void)
Destructor.
Definition: GModels.cpp:122
Definition of interface for container classes.
GModels & operator=(const GModels &models)
Assignment operator.
Definition: GModels.cpp:144
int size(void) const
Return number of models in container.
Definition: GModels.hpp:255
GModel * append(const GModel &model)
Append model to container.
Definition: GModels.cpp:411
Interface class for container classes.
Definition: GContainer.hpp:52
bool is_empty(void) const
Signals if there are no models in container.
Definition: GModels.hpp:269