GammaLib  2.0.0
 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...
 
GVector eval (const GObservation &obs, GMatrixSparse *gradients=NULL) const
 Evaluate sum vector 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 152 of file GModels.hpp.

Constructor & Destructor Documentation

GModels::GModels ( void  )

Void constructor.

Definition at line 73 of file GModels.cpp.

References init_members().

Referenced by clone().

GModels::GModels ( const GModels models)

Copy constructor.

Parameters
[in]modelsModel container.

Definition at line 88 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 109 of file GModels.cpp.

References init_members(), and load().

GModels::~GModels ( void  )
virtual

Destructor.

Definition at line 125 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 420 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 269 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 293 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 217 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 233 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 253 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 670 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 1029 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 911 of file GModels.cpp.

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

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

GVector GModels::eval ( const GObservation obs,
GMatrixSparse gradients = NULL 
) const

Evaluate sum vector of all models.

Parameters
[in]obsObservation.
[in]gradientsPointer to gradients matrix.
Returns
Vector of model values.

Evaluates the sum vector of all models for all events in the observation. Only valid models are considered in this evaluation.

If the gradients pointer is not NULL the method will fill the corresponding matrix with the parameter gradients of the model.

Definition at line 943 of file GModels.cpp.

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

void GModels::extend ( const GModels models)

Append model container.

Parameters
[in]modelsModel container.

Append model container to the container.

Definition at line 621 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 1048 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 1070 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 1010 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()[.
[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 459 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::invalid_argumentModel 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 515 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 273 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 688 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 147 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 231 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 245 of file GModels.hpp.

References m_models.

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

Return pointer to model.

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

Returns a pointer to the model with the specified name.

Definition at line 178 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::invalid_argumentModel with specified name not found in container.

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

Definition at line 205 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 878 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.
Returns
String containing model container information.

Prints all models into a string.

Implements GBase.

Definition at line 972 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::invalid_valueInvalid 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 773 of file GModels.cpp.

References GModelRegistry::alloc(), append(), GXmlElement::attribute(), GRegistry::content(), 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()[.
Exceptions
GException::out_of_rangeModel index is out of range.

Remove model of specified index from container.

Implements GContainer.

Definition at line 560 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::invalid_argumentModel with specified name not found in container.

Remove model of specified name from container.

Definition at line 591 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 287 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 711 of file GModels.cpp.

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

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

Set model in container.

Parameters
[in]indexModel index [0,...,size()[.
[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 321 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::invalid_argumentModel 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 370 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 259 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(), save(), 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 828 of file GModels.cpp.

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

Member Data Documentation

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

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