GammaLib  1.7.0.dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GModels Class Reference

Model container class. More...

#include <GModels.hpp>

Inheritance diagram for GModels:
GContainer GBase

Public Member Functions

 GModels (void)
 Void constructor. More...
 
 GModels (const GModels &models)
 Copy constructor. More...
 
 GModels (const GFilename &filename)
 Load constructor. More...
 
virtual ~GModels (void)
 Destructor. More...
 
GModelsoperator= (const GModels &models)
 Assignment operator. More...
 
GModeloperator[] (const int &index)
 Return pointer to model. More...
 
const GModeloperator[] (const int &index) const
 Return pointer to model (const version) More...
 
GModeloperator[] (const std::string &name)
 Return pointer to model. More...
 
const GModeloperator[] (const std::string &name) const
 Return pointer to model (const version) More...
 
void clear (void)
 Clear object. More...
 
GModelsclone (void) const
 Clone instance. More...
 
std::string classname (void) const
 Return class name. More...
 
GModelat (const int &index)
 Return pointer to model. More...
 
const GModelat (const int &index) const
 Return pointer to model (const version) More...
 
int size (void) const
 Return number of models in container. More...
 
bool is_empty (void) const
 Signals if there are no models in container. More...
 
GModelset (const int &index, const GModel &model)
 Set model in container. More...
 
GModelset (const std::string &name, const GModel &model)
 Set model in container. More...
 
GModelappend (const GModel &model)
 Append model to container. More...
 
GModelinsert (const int &index, const GModel &model)
 Insert model into container. More...
 
GModelinsert (const std::string &name, const GModel &model)
 Insert model into container. More...
 
void remove (const int &index)
 Remove model from container. More...
 
void remove (const std::string &name)
 Remove model from container. More...
 
void reserve (const int &num)
 Reserves space for models in container. More...
 
void extend (const GModels &models)
 Append model container. More...
 
bool contains (const std::string &name) const
 Signals if model name exists. More...
 
void load (const GFilename &filename)
 Load models from XML file. More...
 
void save (const GFilename &filename) const
 Save models into XML file. More...
 
void read (const GXml &xml)
 Read models from XML document. More...
 
void write (GXml &xml) const
 Write models into XML document. More...
 
int npars (void) const
 Return number of model parameters in container. More...
 
GOptimizerPars pars (void) const
 Return optimizer parameter container. More...
 
double eval (const GEvent &event, const GObservation &obs, const bool &gradients=false) const
 Evaluate sum of all models. More...
 
std::string print (const GChatter &chatter=NORMAL) const
 Print models. More...
 
- Public Member Functions inherited from GContainer
virtual ~GContainer (void)
 Destructor. More...
 
- Public Member Functions inherited from GBase
virtual ~GBase (void)
 Destructor. More...
 

Protected Member Functions

void init_members (void)
 Initialise class members. More...
 
void copy_members (const GModels &models)
 Copy class members. More...
 
void free_members (void)
 Delete class members. More...
 
int get_index (const std::string &name) const
 Return model index by name. More...
 

Protected Attributes

std::vector< GModel * > m_models
 List of models. More...
 

Detailed Description

Model container class.

This container class collects models of type GModel that are used to describe the data. The names of all models in the container have to be unique, i.e. every name can occur only once. This allows for accessing the models by name and by index.

The GModels class provides methods to manage and to access the models in the container. The number of models in the container is retrieved using the size() method. The is_empty() method can be used to check whether the container is empty or whether it contains models:

GModels models;                 // Allocate container
int n = models.size();          // Number of models in container
if (models.is_empty())           // Check for emptiness
    std::cout << "Empty container";

Access operators exist for accessing of models by index or by name:

GModel* mptr = models[i];       // Get i'th model
GModel* mptr = models["Crab"];  // Get a model named "Crab"

The index access operator does not check the validity of the provided index. For index validation, use the at() method:

GModel* mptr = models.at(i);    // Get i'th model with index check

The append() method add a model to the container:

models.append(model);           // Append model

The append() method clones the model that is passed as argument. The method returns a pointer to the cloned model so that the attributes of the cloned model can be manipulated:

GModel* mptr = models.append(model);

The insert() methods insert a model before a given index or before a model with a given name (the methods also return a pointer to the cloned model):

models.insert(i, model);        // Insert before i'th model
models.insert("Crab", model);   // Insert before "Crab" model

The set() methods replace an existing model by index or by name (also these methods return a pointer to the cloned model):

models.set(i, model);           // Replace i'th model
models.set("Crab", model);      // Replace "Crab" model

The remove() methods remove an existing model by index or by name:

models.remove(i);               // Remove i'th model
models.remove("Crab");          // Remove "Crab" model

The existence of a model with a given name can be checked using

if (models.contains("Crab"))
    std::cout << "We have the Crab!";

The extend() method extends a container by all models found in another container:

models.extend(other_models);    // Extend container

For repeated container manipulations, a given number of model slots can be reserved using

models.reserve(number);         // Reserves model slots

which will speed up the memory allocations for new models.

Models can be saved into or loaded from an XML file using

models.save("mymodels.xml");    // Save models in XML file
models.load("mymodels.xml");    // Load models from XML file

The models can also be loaded upon construction from an XML file:

GModels models("mymodels.xml"); // Construct by loading models from XML file

The class can also directly operate on a GXml object using the read() and write() methods:

GXml xml;                       // Allocate GXml object
models.write(xml);              // Write into GXml object
models.read(xml);               // Read models from GXml object

The sum of all models in the container are evaluated for a given event and observation using the eval() method:

double value = models.eval(event, observation);

If the eval() method is called with the optional gradients parameter set to true, i.e.

double value = models.eval(event, observation, true);

the method computes also the parameter gradients for all free model parameters that have an analytical parameter gradient.

The only member of GModels is a list of model pointers. The class handles the proper allocation and deallocation of the model memory.

Definition at line 150 of file GModels.hpp.

Constructor & Destructor Documentation

GModels::GModels ( void  )

Void constructor.

Definition at line 70 of file GModels.cpp.

References init_members().

Referenced by clone().

GModels::GModels ( const GModels models)

Copy constructor.

Parameters
[in]modelsModel container.

Definition at line 85 of file GModels.cpp.

References copy_members(), and init_members().

GModels::GModels ( const GFilename filename)
explicit

Load constructor.

Parameters
[in]filenameXML filename.

Constructs model container from an XML file. See the read() method for more information about the expected structure of the XML file.

Definition at line 106 of file GModels.cpp.

References init_members(), and load().

GModels::~GModels ( void  )
virtual

Destructor.

Definition at line 122 of file GModels.cpp.

References free_members().

Member Function Documentation

GModel * GModels::append ( const GModel model)

Append model to container.

Parameters
[in]modelModel.
Returns
Pointer to deep copy of model.
Exceptions
GException::invalid_valueName of model exists already in container.

Appends model to the container by making a deep copy of the model and storing its pointer.

Definition at line 411 of file GModels.cpp.

References GModel::clone(), G_APPEND, get_index(), m_models, GModel::name(), and gammalib::str().

Referenced by read(), and GCTAOnOffObservation::set().

GModel * GModels::at ( const int &  index)

Return pointer to model.

Parameters
[in]indexModel index [0,...,size()-1].
Exceptions
GException::out_of_rangeModel index is out of range.

Returns a pointer to the model with the specified index.

Definition at line 262 of file GModels.cpp.

References G_AT, m_models, and size().

const GModel * GModels::at ( const int &  index) const

Return pointer to model (const version)

Parameters
[in]indexModel index [0,...,size()-1].
Exceptions
GException::out_of_rangeModel index is out of range.

Returns a const pointer to the model with the specified index.

Definition at line 286 of file GModels.cpp.

References G_AT, m_models, and size().

std::string GModels::classname ( void  ) const
inlinevirtual

Return class name.

Returns
String containing the class name ("GModels").

Implements GBase.

Definition at line 213 of file GModels.hpp.

Referenced by GCTAOnOffObservation::set().

void GModels::clear ( void  )
virtual

Clear object.

Removes all models from the container.

Implements GBase.

Definition at line 226 of file GModels.cpp.

References free_members(), and init_members().

Referenced by GObservations::init_members(), and load().

GModels * GModels::clone ( void  ) const
virtual

Clone instance.

Returns
Pointer to deep copy of model container

Makes a deep copy of the model container instance.

Implements GBase.

Definition at line 246 of file GModels.cpp.

References GModels().

Referenced by extend().

bool GModels::contains ( const std::string &  name) const

Signals if model name exists.

Parameters
[in]nameModel name.
Returns
True if model with specified name exists.

Searches all model names for a match with the specified name. If the specified name has been found, true is returned.

Definition at line 654 of file GModels.cpp.

References get_index().

Referenced by GObservations::npred().

void GModels::copy_members ( const GModels models)
protected

Copy class members.

Parameters
[in]modelsModel container.

Makes a copy of all class members. All models are deep copied, and the linear pointer array for parameter access through the GOptimizerPars base class is set.

Definition at line 955 of file GModels.cpp.

References m_models.

Referenced by GModels(), and operator=().

double GModels::eval ( const GEvent event,
const GObservation obs,
const bool &  gradients = false 
) const

Evaluate sum of all models.

Parameters
[in]eventObserved event.
[in]obsObservation.
[in]gradientsCompute gradients?
Returns
Value of models.

Evaluates the sum of all models for the specified event and observation. Only valid models are considered in this evaluation.

If the gradients flag is true the method will also set the parameter gradients of the model parameters.

Definition at line 871 of file GModels.cpp.

References GObservation::id(), GObservation::instrument(), m_models, and size().

Referenced by GCTAOnOffObservation::compute_alpha(), GCTAOnOffObservation::compute_bgd(), and GCOMObservation::drm().

void GModels::extend ( const GModels models)

Append model container.

Parameters
[in]modelsModel container.

Append model container to the container.

Definition at line 605 of file GModels.cpp.

References clone(), G_EXTEND, get_index(), is_empty(), m_models, reserve(), size(), and gammalib::str().

void GModels::free_members ( void  )
protected

Delete class members.

Deallocates all models. The method loops over the model container and deallocates the memory that has been allocated before.

Definition at line 974 of file GModels.cpp.

References m_models.

Referenced by clear(), operator=(), and ~GModels().

int GModels::get_index ( const std::string &  name) const
protected

Return model index by name.

Parameters
[in]nameModel name.
Returns
Model index (-1 if model name has not been found)

Returns model index based on the specified name. If no model with the specified name is found the method returns -1.

Definition at line 996 of file GModels.cpp.

References m_models, and size().

Referenced by append(), contains(), extend(), insert(), operator[](), remove(), and set().

void GModels::init_members ( void  )
protected

Initialise class members.

Definition at line 936 of file GModels.cpp.

References m_models.

Referenced by clear(), GModels(), and operator=().

GModel * GModels::insert ( const int &  index,
const GModel model 
)

Insert model into container.

Parameters
[in]indexModel index [0,...,size()-1].
[in]modelModel.
Returns
Pointer to deep copy of model.
Exceptions
GException::out_of_rangeModel index is out of range.
GException::invalid_valueName of model exists already in container.

Inserts a model into the container before the model with the specified index.

Definition at line 450 of file GModels.cpp.

References GModel::clone(), G_INSERT1, get_index(), is_empty(), m_models, GModel::name(), size(), and gammalib::str().

GModel * GModels::insert ( const std::string &  name,
const GModel model 
)

Insert model into container.

Parameters
[in]nameModel name.
[in]modelModel.
Returns
Pointer to deep copy of model.
Exceptions
GException::model_not_foundModel with specified name not found in container.
GException::invalid_valueName of model exists already in container.

Inserts a model into the container before the model with the specified name.

Definition at line 504 of file GModels.cpp.

References GModel::clone(), G_INSERT2, get_index(), m_models, GModel::name(), and gammalib::str().

bool GModels::is_empty ( void  ) const
inlinevirtual

Signals if there are no models in container.

Returns
True if container is empty, false otherwise.

Signals if the model container does not contain any model.

Implements GContainer.

Definition at line 269 of file GModels.hpp.

References m_models.

Referenced by extend(), and insert().

void GModels::load ( const GFilename filename)

Load models from XML file.

Parameters
[in]filenameXML filename.

Loads all models from an XML file. See the read() method for more information about the expected structure of the XML file.

Definition at line 672 of file GModels.cpp.

References clear(), read(), and GFilename::url().

Referenced by GModels(), and GObservations::models().

int GModels::npars ( void  ) const
GModels & GModels::operator= ( const GModels models)

Assignment operator.

Parameters
[in]modelsModel container.
Returns
Model container.

Definition at line 144 of file GModels.cpp.

References copy_members(), free_members(), and init_members().

GModel * GModels::operator[] ( const int &  index)
inline

Return pointer to model.

Parameters
[in]indexModel index [0,...,size()-1].

Returns a pointer to the model with the specified index.

Definition at line 227 of file GModels.hpp.

References m_models.

const GModel * GModels::operator[] ( const int &  index) const
inline

Return pointer to model (const version)

Parameters
[in]indexModel index [0,...,size()-1].

Returns a const pointer to the model with the specified index.

Definition at line 241 of file GModels.hpp.

References m_models.

GModel * GModels::operator[] ( const std::string &  name)

Return pointer to model.

Parameters
[in]nameModel name.
Exceptions
GException::model_not_foundModel with specified name not found in container.

Returns a pointer to the model with the specified name.

Definition at line 175 of file GModels.cpp.

References G_ACCESS, get_index(), and m_models.

const GModel * GModels::operator[] ( const std::string &  name) const

Return pointer to model (const version)

Parameters
[in]nameModel name.
Exceptions
GException::model_not_foundModel with specified name not found in container.

Returns a const pointer to the model with the specified name.

Definition at line 200 of file GModels.cpp.

References G_ACCESS, get_index(), and m_models.

GOptimizerPars GModels::pars ( void  ) const

Return optimizer parameter container.

Returns
Optimizer parameter container.

Returns an optimizer parameter container that is built by extracting all model pointers from the model and attaching them to the parameter container. The optimizer parameter container will thus contains a flat array of a model parameters.

Definition at line 838 of file GModels.cpp.

References GOptimizerPars::attach(), m_models, npars(), GModel::size(), and size().

Referenced by GObservations::errors(), GObservations::errors_hessian(), GObservations::eval(), and GObservations::optimize().

std::string GModels::print ( const GChatter chatter = NORMAL) const
virtual

Print models.

Parameters
[in]chatterChattiness (defaults to NORMAL).
Returns
String containing model container information.

Prints all models into a string.

Implements GBase.

Definition at line 898 of file GModels.cpp.

References m_models, npars(), gammalib::parformat(), SILENT, size(), and gammalib::str().

Referenced by GObservations::print().

void GModels::read ( const GXml xml)

Read models from XML document.

Parameters
[in]xmlXML document.
Exceptions
GException::model_invalidInvalid model type encountered.

Read models from the first source library found in the XML document. The XML document is expected to have the following structure

<source_library title="source library">
  <source name="Source1" type="PointSource">
    ...
  </source>
  <source name="Source2" type="DiffuseSource">
    ...
  </source>
</source_library>

Each source tag will be interpreted as a model component.

Todo:
Sources names are not verified so far for uniqueness. This would be required to achieve an unambiguous update of parameters in an already existing XML file when using the write method.

Definition at line 737 of file GModels.cpp.

References GModelRegistry::alloc(), append(), GXmlElement::attribute(), GXmlNode::element(), GXml::element(), GXmlNode::elements(), G_READ, and GModel::read().

Referenced by load().

void GModels::remove ( const int &  index)
virtual

Remove model from container.

Parameters
[in]indexModel index [0,...,size()-1].
Exceptions
GException::out_of_rangeModel index is out of range.

Remove model of specified index from container.

Implements GContainer.

Definition at line 547 of file GModels.cpp.

References G_REMOVE1, m_models, and size().

void GModels::remove ( const std::string &  name)

Remove model from container.

Parameters
[in]nameModel name.
Exceptions
GException::model_not_foundModel with specified name not found in container.

Remove model of specified name from container.

Definition at line 577 of file GModels.cpp.

References G_REMOVE2, get_index(), and m_models.

void GModels::reserve ( const int &  num)
inlinevirtual

Reserves space for models in container.

Parameters
[in]numNumber of models

Reserves space for num models in the container.

Implements GContainer.

Definition at line 283 of file GModels.hpp.

References m_models.

Referenced by extend().

void GModels::save ( const GFilename filename) const

Save models into XML file.

Parameters
[in]filenameXML filename.

Saves all models in the container into an XML file.

Definition at line 695 of file GModels.cpp.

References GXml::save(), and write().

GModel * GModels::set ( const int &  index,
const GModel model 
)

Set model in container.

Parameters
[in]indexModel index [0,...,size()-1].
[in]modelModel.
Returns
Pointer to deep copy of model.
Exceptions
GException::out_of_rangeModel index is out of range.
GException::invalid_valueName of model exists already in container.

Set model in the container. A deep copy of the model will be made.

Definition at line 314 of file GModels.cpp.

References GModel::clone(), G_SET1, get_index(), m_models, GModel::name(), size(), and gammalib::str().

GModel * GModels::set ( const std::string &  name,
const GModel model 
)

Set model in container.

Parameters
[in]nameModel name.
[in]modelModel pointer.
Returns
Pointer to deep copy of model.
Exceptions
GException::model_not_foundModel with specified name not found in container.
GException::invalid_valueName of model exists already in container.

Set model in the container. A deep copy of the model will be made.

Definition at line 363 of file GModels.cpp.

References GModel::clone(), G_SET2, get_index(), m_models, GModel::name(), and gammalib::str().

int GModels::size ( void  ) const
inlinevirtual

Return number of models in container.

Returns
Number of models in container.

Returns the number of models in the model container.

Implements GContainer.

Definition at line 255 of file GModels.hpp.

References m_models.

Referenced by at(), eval(), extend(), get_index(), insert(), GObservation::model(), GCTAOnOffObservation::N_bgd(), GCTAOnOffObservation::N_gamma(), npars(), GObservation::npred(), pars(), GObservations::print(), print(), remove(), GObservations::remove_response_cache(), GCTAOnOffObservation::set(), set(), and write().

void GModels::write ( GXml xml) const

Write models into XML document.

Parameters
[in]xmlXML document.

Write models into the first source library that is found in the XML document. In case that no source library exists, one is added to the document.

Definition at line 788 of file GModels.cpp.

References GXml::append(), GXml::element(), GXml::elements(), m_models, and size().

Referenced by save().

Member Data Documentation

std::vector<GModel*> GModels::m_models
protected

The documentation for this class was generated from the following files: