Model container class. More...

#include <GModels.hpp>

Inheritance diagram for GModels:

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...

GModels &	operator= (const GModels &models)
	Assignment operator. More...

GModel *	operator[] (const int &index)
	Return pointer to model. More...

const GModel *	operator[] (const int &index) const
	Return pointer to model (const version) More...

GModel *	operator[] (const std::string &name)
	Return pointer to model. More...

const GModel *	operator[] (const std::string &name) const
	Return pointer to model (const version) More...

void	clear (void)
	Clear object. More...

GModels *	clone (void) const
	Clone instance. More...

std::string	classname (void) const
	Return class name. More...

GModel *	at (const int &index)
	Return pointer to model. More...

const GModel *	at (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...

GModel *	set (const int &index, const GModel &model)
	Set model in container. More...

GModel *	set (const std::string &name, const GModel &model)
	Set model in container. More...

GModel *	append (const GModel &model)
	Append model to container. More...

GModel *	insert (const int &index, const GModel &model)
	Insert model into container. More...

GModel *	insert (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] models Model 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] filename XML 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] model Model.

Returns: Pointer to deep copy of model.

Exceptions

GException::invalid_value Name 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] index Model index [0,...,size()-1].

Exceptions

GException::out_of_range Model 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] index Model index [0,...,size()-1].

Exceptions

GException::out_of_range Model 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] name Model 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] models Model 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]	event	Observed event.
[in]	obs	Observation.
[in]	gradients	Compute 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]	obs	Observation.
[in]	gradients	Pointer 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] models Model 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] name Model 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]	index	Model index [0,...,size()[.
[in]	model	Model.

Returns: Pointer to deep copy of model.

Exceptions

GException::out_of_range	Model index is out of range.
GException::invalid_value	Name 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]	name	Model name.
[in]	model	Model.

Returns: Pointer to deep copy of model.

Exceptions

GException::invalid_argument	Model with specified name not found in container.
GException::invalid_value	Name 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] filename XML 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

Return number of model parameters in container.

Returns: Number of model parameters in container.

Definition at line 853 of file GModels.cpp.

References m_models, and size().

Referenced by GCTAOnOffObservation::likelihood_cstat(), GCTAOnOffObservation::likelihood_wstat(), GObservation::model(), GCTAOnOffObservation::model_background(), GCTAOnOffObservation::model_gamma(), GCTAOnOffObservation::N_bgd(), GCTAOnOffObservation::N_gamma(), GObservation::npred(), pars(), and print().

GModels & GModels::operator= ( const GModels & models )

Assignment operator.

Parameters

[in] models Model 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] index Model 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] index Model 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] name Model name.

Exceptions

GException::invalid_argument Model 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] name Model name.

Exceptions

GException::invalid_argument Model 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] chatter Chattiness.

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] xml XML document.

Exceptions

GException::invalid_value Invalid 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] index Model index [0,...,size()[.

Exceptions

GException::out_of_range Model 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] name Model name.

Exceptions

GException::invalid_argument Model 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] num Number 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] filename XML 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]	index	Model index [0,...,size()[.
[in]	model	Model.

Returns: Pointer to deep copy of model.

Exceptions

GException::out_of_range	Model index is out of range.
GException::invalid_value	Name 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]	name	Model name.
[in]	model	Model pointer.

Returns: Pointer to deep copy of model.

Exceptions

GException::invalid_argument	Model with specified name not found in container.
GException::invalid_value	Name 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] xml XML 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

List of models.

Definition at line 207 of file GModels.hpp.

Referenced by append(), at(), copy_members(), eval(), extend(), free_members(), get_index(), init_members(), insert(), is_empty(), npars(), operator[](), pars(), print(), remove(), reserve(), save(), set(), size(), and write().

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

include/GModels.hpp
src/model/GModels.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation