GammaLib  2.1.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GModelSky.hpp
Go to the documentation of this file.
1 /***************************************************************************
2  * GModelSky.hpp - Sky model class *
3  * ----------------------------------------------------------------------- *
4  * copyright (C) 2011-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 GModelSky.hpp
23  * @brief Sky model class interface definition
24  * @author Juergen Knoedlseder
25  */
26 
27 #ifndef GMODELSKY_HPP
28 #define GMODELSKY_HPP
29 
30 /* __ Includes ___________________________________________________________ */
31 #include <string>
32 #include "GFunction.hpp"
33 #include "GModel.hpp"
34 #include "GModelPar.hpp"
35 #include "GModelSpatial.hpp"
36 #include "GModelSpectral.hpp"
37 #include "GModelTemporal.hpp"
38 #include "GSkyDir.hpp"
39 #include "GEnergy.hpp"
40 #include "GTime.hpp"
41 #include "GPhoton.hpp"
42 #include "GPhotons.hpp"
43 #include "GRan.hpp"
44 #include "GEvent.hpp"
45 #include "GObservation.hpp"
46 #include "GXmlElement.hpp"
47 
48 /* __ Forward declarations _______________________________________________ */
49 class GEvent;
50 class GObservation;
51 class GVector;
52 class GMatrixSparse;
53 
54 
55 /***********************************************************************//**
56  * @class GModelSky
57  *
58  * @brief Sky model class
59  *
60  * This class implements a sky model that is factorized into a spatial,
61  * a spectral and a temporal component. The factorization is given by
62  *
63  * \f[
64  * S(\vec{p}, E, t) = S_{\rm p}(\vec{p} | E, t) \,
65  * S_{\rm E}(E | t) \,
66  * S_{\rm t}(t)
67  * \f]
68  *
69  * where
70  * - \f$S_{\rm p}(\vec{p} | E, t)\f$ is the spatial component,
71  * - \f$S_{\rm E}(E | t)\f$ is the spectral component, and
72  * - \f$S_{\rm t}(t)\f$ is the temporal component.
73  *
74  * The spatial component describes the energy and time dependent morphology
75  * of the source. It satisfies
76  * \f[
77  * \int_{\Omega} S_{\rm p}(\vec{p} | E, t) d\Omega = 1
78  * \f]
79  * for all \f$E\f$ and \f$t\f$, hence the spatial component does not
80  * impact the spatially integrated spectral and temporal properties of the
81  * source.
82  *
83  * The spectral component describes the spatially integrated time dependent
84  * spectral distribution of the source. It satisfies
85  * \f[
86  * \int_{E} S_{\rm E}(E | t) dE = \Phi
87  * \f]
88  * for all \f$t\f$, where \f$\Phi\f$ is the spatially and spectrally
89  * integrated total source flux. The spectral component does not impact
90  * the temporal properties of the integrated flux \f$\Phi\f$.
91  *
92  * The temporal component describes the temporal variation of the total
93  * integrated flux \f$\Phi\f$ of the source.
94  *
95  * The class has two methods for model evaluation that evaluate the model
96  * for a specific event, given an observation. The eval() method returns
97  * the model value. Note that the eval() method calls protected methods that
98  * handle time dispersion, energy dispersion and the point
99  * spread function (spatial dispersion). Dispersion is handled by
100  * integrating over the relevant intervals of the source properties.
101  * Integration of the model is done by three nested integrals.
102  * The outmost integral integrates over time (method integrate_time()),
103  * the next integral integrates over energy (method integrate_energy()),
104  * and the innermost integral integrates over the point spread function
105  * (method integrate_dir()).
106  *
107  * The npred() method returns the integral over the model for a given
108  * observed energy and time.
109  *
110  * The read() and write() methods allow reading of model information from
111  * and writing to an XML element. The type() method returns the model type
112  * that has been found in an XML element.
113  *
114  * The model factorization is implemented by the abstract model component
115  * classes GModelSpatial, GModelSpectral and GModelTemporal. The GModelSky
116  * class holds pointers to derived instances of these classes, which can
117  * be accessed using the spatial(), spectral() and temporal() methods. Note
118  * that these pointers can be NULL (for example if no model has been yet
119  * defined), so the validity of the pointers needs to be checked before
120  * using them.
121  ***************************************************************************/
122 class GModelSky : public GModel {
123 
124 public:
125  // Constructors and destructors
126  GModelSky(void);
127  explicit GModelSky(const std::string& type);
128  explicit GModelSky(const GXmlElement& xml);
130  const GXmlElement& spectral);
131  GModelSky(const GXmlElement& spatial,
132  const GXmlElement& spectral,
133  const GXmlElement& temporal);
134  GModelSky(const GModelSpatial& spatial,
135  const GModelSpectral& spectral);
136  GModelSky(const GModelSpatial& spatial,
137  const GModelSpectral& spectral,
138  const GModelTemporal& temporal);
139  GModelSky(const GModelSky& model);
140  virtual ~GModelSky(void);
141 
142  // Operators
143  virtual GModelSky& operator=(const GModelSky& model);
144 
145  // Implemented pure virtual base class methods
146  virtual void clear(void);
147  virtual GModelSky* clone(void) const;
148  virtual std::string classname(void) const;
149  virtual std::string type(void) const;
150  virtual bool is_constant(void) const;
151  virtual double eval(const GEvent& event,
152  const GObservation& obs,
153  const bool& gradients = false) const;
154  virtual GVector eval(const GObservation& obs,
155  GMatrixSparse* gradients = NULL) const;
156  virtual double npred(const GEnergy& obsEng,
157  const GTime& obsTime,
158  const GObservation& obs) const;
159  virtual void read(const GXmlElement& xml);
160  virtual void write(GXmlElement& xml) const;
161  virtual std::string print(const GChatter& chatter = NORMAL) const;
162 
163  // Other methods
164  GModelSpatial* spatial(void) const;
165  GModelSpectral* spectral(void) const;
166  GModelTemporal* temporal(void) const;
167  void spatial(const GModelSpatial* spatial);
168  void spectral(const GModelSpectral* spectral);
169  void temporal(const GModelTemporal* temporal);
170  double value(const GPhoton& photon);
171  GVector gradients(const GPhoton& photon);
172  GPhotons mc(const double& area,
173  const GSkyDir& dir, const double& radius,
174  const GEnergy& emin, const GEnergy& emax,
175  const GTime& tmin, const GTime& tmax,
176  GRan& ran) const;
177  double flux(const GEnergy& emin,
178  const GEnergy& emax) const;
179  double flux(const GSkyRegion& region,
180  const GEnergy& emin,
181  const GEnergy& emax) const;
182  double eflux(const GEnergy& emin,
183  const GEnergy& emax) const;
184  double eflux(const GSkyRegion& region,
185  const GEnergy& emin,
186  const GEnergy& emax) const;
187  double flux_error(const GEnergy& emin,
188  const GEnergy& emax) const;
189  double flux_error(const GSkyRegion& region,
190  const GEnergy& emin,
191  const GEnergy& emax) const;
192  double eflux_error(const GEnergy& emin,
193  const GEnergy& emax) const;
194  double eflux_error(const GSkyRegion& region,
195  const GEnergy& emin,
196  const GEnergy& emax) const;
197 
198 protected:
199  // Protected methods
200  void init_members(void);
201  void copy_members(const GModelSky& model);
202  void free_members(void);
203  void set_pointers(void);
204  void set_type(void);
205  void signal_analytical_gradients(const GObservation& obs) const;
206  GModelSpatial* xml_spatial(const GXmlElement& spatial) const;
207  GModelSpectral* xml_spectral(const GXmlElement& spectral) const;
208  GModelTemporal* xml_temporal(const GXmlElement& temporal) const;
209  bool valid_model(void) const;
210 
211  // Flux integration kernels
212  class flux_kern : public GFunction {
213  public:
214  flux_kern(const GModelSky* parent,
215  const GSkyRegion* region) :
216  m_parent(parent),
217  m_region(region) { }
218  double eval(const double& x);
219  protected:
220  const GModelSky* m_parent; //!< Sky model
221  const GSkyRegion* m_region; //!< Sky region
222  };
223  class eflux_kern : public GFunction {
224  public:
225  eflux_kern(const GModelSky* parent,
226  const GSkyRegion* region) :
227  m_parent(parent),
228  m_region(region) { }
229  double eval(const double& x);
230  protected:
231  const GModelSky* m_parent; //!< Sky model
232  const GSkyRegion* m_region; //!< Sky region
233  };
234 
235  // Protected data members
236  std::string m_type; //!< Model type
237  GModelSpatial* m_spatial; //!< Spatial model
238  GModelSpectral* m_spectral; //!< Spectral model
239  GModelTemporal* m_temporal; //!< Temporal model
240 };
241 
242 
243 /***********************************************************************//**
244  * @brief Return class name
245  *
246  * @return String containing the class name ("GModelSky").
247  ***************************************************************************/
248 inline
249 std::string GModelSky::classname(void) const
250 {
251  return ("GModelSky");
252 }
253 
254 
255 /***********************************************************************//**
256  * @brief Return sky model type
257  *
258  * @return Sky model type.
259  *
260  * Returns the type of the sky model. The type is an arbitrary string that
261  * is used in the XML declaration of the model to describe the model type.
262  ***************************************************************************/
263 inline
264 std::string GModelSky::type(void) const
265 {
266  return (m_type);
267 }
268 
269 
270 /***********************************************************************//**
271  * @brief Signals if sky model is temporally constant
272  *
273  * @return True if sky model is temporally constant, false otherwise.
274  *
275  * Signals if the sky model is temporally constant. A temporally constant
276  * model is a model that has a temporal component of type "Constant".
277  ***************************************************************************/
278 inline
279 bool GModelSky::is_constant(void) const
280 {
281  return (m_temporal != NULL && m_temporal->type() == "Constant");
282 }
283 
284 
285 /***********************************************************************//**
286  * @brief Return spatial model component
287  *
288  * @return Pointer to spatial model component.
289  *
290  * Returns a pointer to the spatial model component of the model. The pointer
291  * is of type GModelSpatial. Note that a NULL pointer may be returned if the
292  * sky model has no spatial model component.
293  ***************************************************************************/
294 inline
296 {
297  return (m_spatial);
298 }
299 
300 
301 /***********************************************************************//**
302  * @brief Return spectral model component
303  *
304  * @return Pointer to spectral model component.
305  *
306  * Returns a pointer to the spectral model component of the model. The
307  * pointer is of type GModelSpectral. Note that a NULL pointer may be
308  * returned if the sky model has no spectral model component.
309  ***************************************************************************/
310 inline
312 {
313  return (m_spectral);
314 }
315 
316 
317 /***********************************************************************//**
318  * @brief Return temporal model component
319  *
320  * @return Pointer to temporal model component.
321  *
322  * Returns a pointer to the temporal model component of the model. The
323  * pointer is of type GModelTemporal. Note that a NULL pointer may be
324  * returned if the sky model has no temporal model component.
325  ***************************************************************************/
326 inline
328 {
329  return (m_temporal);
330 }
331 
332 #endif /* GMODELSKY_HPP */
Abstract model class.
Definition: GModel.hpp:100
void set_type(void)
Set model type based on spatial model component.
Definition: GModelSky.cpp:2032
const GModelSky * m_parent
Sky model.
Definition: GModelSky.hpp:231
Abstract model base class interface definition.
GModelTemporal * m_temporal
Temporal model.
Definition: GModelSky.hpp:239
Energy value class definition.
Random number generator class definition.
Abstract spectral model base class.
Sparse matrix class interface definition.
XML element node class interface definition.
void copy_members(const GModelSky &model)
Copy class members.
Definition: GModelSky.cpp:1935
GModelSpectral * spectral(void) const
Return spectral model component.
Definition: GModelSky.hpp:311
GModelTemporal * xml_temporal(const GXmlElement &temporal) const
Return pointer to temporal model from XML element.
Definition: GModelSky.cpp:2175
double eflux_error(const GEnergy &emin, const GEnergy &emax) const
Return sky model energy flux error.
Definition: GModelSky.cpp:1575
Abstract temporal model base class.
GPhotons mc(const double &area, const GSkyDir &dir, const double &radius, const GEnergy &emin, const GEnergy &emax, const GTime &tmin, const GTime &tmax, GRan &ran) const
Return simulated list of photons.
Definition: GModelSky.cpp:882
Sky direction class interface definition.
virtual void clear(void)
Clear sky model.
Definition: GModelSky.cpp:379
GModelSpatial * xml_spatial(const GXmlElement &spatial) const
Return pointer to spatial model from XML element.
Definition: GModelSky.cpp:2137
GModelTemporal * temporal(void) const
Return temporal model component.
Definition: GModelSky.hpp:327
void signal_analytical_gradients(const GObservation &obs) const
Signal all parameters that have analytical gradients for a given observation.
Definition: GModelSky.cpp:2087
Abstract interface for the event classes.
Definition: GEvent.hpp:71
void set_pointers(void)
Set parameter pointers.
Definition: GModelSky.cpp:1979
XML element node class.
Definition: GXmlElement.hpp:48
virtual ~GModelSky(void)
Destructor.
Definition: GModelSky.cpp:322
const GSkyRegion * m_region
Sky region.
Definition: GModelSky.hpp:232
Abstract spatial model base class interface definition.
Random number generator class.
Definition: GRan.hpp:44
bool valid_model(void) const
Verifies if model has all components.
Definition: GModelSky.cpp:2191
Photon container class.
Definition: GPhotons.hpp:45
Time class.
Definition: GTime.hpp:55
const GModelSky * m_parent
Sky model.
Definition: GModelSky.hpp:220
std::string m_type
Model type.
Definition: GModelSky.hpp:236
GModelSpectral * m_spectral
Spectral model.
Definition: GModelSky.hpp:238
Photon container class definition.
double flux_error(const GEnergy &emin, const GEnergy &emax) const
Return sky model photon flux error.
Definition: GModelSky.cpp:1299
virtual bool is_constant(void) const
Signals if sky model is temporally constant.
Definition: GModelSky.hpp:279
Model parameter class interface definition.
virtual void write(GXmlElement &xml) const
Write model into XML element.
Definition: GModelSky.cpp:793
Class that handles photons.
Definition: GPhoton.hpp:47
flux_kern(const GModelSky *parent, const GSkyRegion *region)
Definition: GModelSky.hpp:214
eflux_kern(const GModelSky *parent, const GSkyRegion *region)
Definition: GModelSky.hpp:225
Abstract temporal model base class interface definition.
Abstract interface for the sky region class.
Definition: GSkyRegion.hpp:57
double eval(const double &x)
Integration kernel for flux_kern() class.
Definition: GModelSky.cpp:2212
Single parameter function abstract base class definition.
GVector gradients(const GPhoton &photon)
Return parameter gradients of sky model for a given photon.
Definition: GModelSky.cpp:529
double eflux(const GEnergy &emin, const GEnergy &emax) const
Return sky model energy flux.
Definition: GModelSky.cpp:1173
double eval(const double &x)
Integration kernel for eflux_kern() class.
Definition: GModelSky.cpp:2242
virtual double npred(const GEnergy &obsEng, const GTime &obsTime, const GObservation &obs) const
Return spatially integrated sky model.
Definition: GModelSky.cpp:648
const GSkyRegion * m_region
Sky region.
Definition: GModelSky.hpp:221
Abstract event base class definition.
virtual void read(const GXmlElement &xml)
Read sky model from XML element.
Definition: GModelSky.cpp:724
GChatter
Definition: GTypemaps.hpp:33
Abstract observation base class.
virtual GModelSky * clone(void) const
Clone sky model.
Definition: GModelSky.cpp:399
Photon class definition.
Abstract observation base class interface definition.
virtual GModelSky & operator=(const GModelSky &model)
Assignment operator.
Definition: GModelSky.cpp:344
Abstract spectral model base class interface definition.
double value(const GPhoton &photon)
Return value of sky model for a given photon.
Definition: GModelSky.cpp:503
virtual std::string type(void) const =0
Sky model class.
Definition: GModelSky.hpp:122
Single parameter function abstract base class.
Definition: GFunction.hpp:44
void init_members(void)
Initialise class members.
Definition: GModelSky.cpp:1917
virtual std::string type(void) const
Return sky model type.
Definition: GModelSky.hpp:264
GModelSpatial * m_spatial
Spatial model.
Definition: GModelSky.hpp:237
GModelSpatial * spatial(void) const
Return spatial model component.
Definition: GModelSky.hpp:295
Abstract spatial model base class.
GModelSky(void)
Void constructor.
Definition: GModelSky.cpp:91
Vector class.
Definition: GVector.hpp:46
double flux(const GEnergy &emin, const GEnergy &emax) const
Return sky model photon flux.
Definition: GModelSky.cpp:1061
virtual std::string print(const GChatter &chatter=NORMAL) const
Print model information.
Definition: GModelSky.cpp:1837
Sky direction class.
Definition: GSkyDir.hpp:62
virtual std::string classname(void) const
Return class name.
Definition: GModelSky.hpp:249
Time class interface definition.
virtual double eval(const GEvent &event, const GObservation &obs, const bool &gradients=false) const
Evaluate sky model for a given event of an observation.
Definition: GModelSky.cpp:565
void free_members(void)
Delete class members.
Definition: GModelSky.cpp:1956
Class that handles energies in a unit independent way.
Definition: GEnergy.hpp:48
GModelSpectral * xml_spectral(const GXmlElement &spectral) const
Return pointer to spectral model from XML element.
Definition: GModelSky.cpp:2156