IMP::Model Class Reference

---

Detailed Description

Class for storing model, its restraints, constraints, and particles.

The Model maintains a standard IMP container for each of Particle, ScoreState and Restraint object types.

Note:

Think carefully about using the iterators over the entire set of Particles or Restraints. Most operations should be done using a user-passed set of Particles or Restraints instead.

Inheritance diagram for IMP::Model:

[legend]

Public Member Functions
def	__del__
virtual Float	evaluate (const RestraintsTemp &restraints, bool calc_derivs)
	Evaluate a subset of the restraints.
virtual Float	evaluate (bool calc_derivs)
	Evaluate all of the restraints in the model and return the score.
	Model ()
void	remove_particle (Particle *p)
	Remove the particle from this model.
void	restore_particle (Particle *p)
	Sometimes it is useful to put a particle back into a model.
Incremental Updates
Control whether incremental updates are being used. See the incremental updates page for a more detailed description.
bool	get_is_incremental () const
void	set_is_incremental (bool tf)
Methods to debug particles
It is sometimes useful to inspect the list of all particles when debugging. These methods allow you to do that. Note: Only use this if you really know what you are doing as Particles can be added to the object from many different places. The value type for the iterators is a Particle*.
unsigned int	get_number_of_particles () const
ParticleConstIterator	particles_begin () const
ParticleIterator	particles_begin ()
ParticleConstIterator	particles_end () const
ParticleIterator	particles_end ()
Float Attribute Ranges
Each Float attribute has an associated range which reflects the range of values that it is expected to take on during optimization. The optimizer can use these ranges to make the optimization process more efficient. By default, the range estimates are simply the range of values for that attribute in the various particles, but it can be set to another value. For example, an attribute storing an angle could have the range set to (0,PI). The ranges are not enforced; they are just guidelines. In order to enforce ranges, see, for example, IMP::example::ExampleSingletonModifier.
FloatRange	get_range (FloatKey k) const
void	set_range (FloatKey k, FloatRange range)
Statistics
The Model can gather various statistics about the restraints and score states used. To use this feature, first turn on statistics gather and then run your optimization (or just call evaluate). Note: Telling the model not to gather statistics does not clear existing statistics.
void	set_gather_statistics (bool tf)
void	show_statistics_summary (std::ostream &out=std::cout) const
Restraints
The Model scores the current configuration using the stored Restraint objects. Use the methods below to manipulate the list. The value type for the iterators is a Restraint*.
unsigned int	add_restraint (Restraint *obj)
void	add_restraints (const Restraints &obj)
void	clear_restraints ()
bool	get_has_restraints () const
	return true if there are any objects in the container
unsigned int	get_number_of_restraints () const
Restraint *	get_restraint (unsigned int i) const
void	remove_restraint (Restraint *d)
	Remove any occurences of d from the container.
void	remove_restraints (const Restraints &d)
	Remove any occurences of each item in d.
template<class F >
void	remove_restraints_if (const F &f)
	Remove any occurrences for which f is true.
void	reserve_restraints (unsigned int sz)
RestraintConstIterator	restraints_begin () const
RestraintIterator	restraints_begin ()
RestraintConstIterator	restraints_end () const
RestraintIterator	restraints_end ()
void	set_restraints (const Restraints &ps)
States
The Model stores a list of ScoreStates which are given an opportunity to update the stored Particles and their internal state before and after the restraints are evaluated. Use the methods below to manipulate the list of ScoreState objects. The value type for the iterators is a ScoreState*. Note: The order of addition of ScoreState objects does not matter. Familiarity with these methods is not required to use imp.
unsigned int	add_score_state (ScoreState *obj)
void	add_score_states (const ScoreStates &obj)
void	clear_score_states ()
bool	get_has_score_states () const
	return true if there are any objects in the container
unsigned int	get_number_of_score_states () const
ScoreState *	get_score_state (unsigned int i) const
void	remove_score_state (ScoreState *d)
	Remove any occurences of d from the container.
void	remove_score_states (const ScoreStates &d)
	Remove any occurences of each item in d.
template<class F >
void	remove_score_states_if (const F &f)
	Remove any occurrences for which f is true.
void	reserve_score_states (unsigned int sz)
ScoreStateConstIterator	score_states_begin () const
ScoreStateIterator	score_states_begin ()
ScoreStateConstIterator	score_states_end () const
ScoreStateIterator	score_states_end ()
void	set_score_states (const ScoreStates &ps)

---

Constructor & Destructor Documentation

IMP::Model::Model

(

)

Construct an empty model

---

Member Function Documentation

unsigned int IMP::Model::add_restraint

(

Restraint *

obj

)

Returns:

index of object within the object

void IMP::Model::add_restraints

(

const Restraints &

obj

)

Add several objects to the container. They are not necessarily added at the end.

unsigned int IMP::Model::add_score_state

(

ScoreState *

obj

)

Returns:

index of object within the object

void IMP::Model::add_score_states

(

const ScoreStates &

obj

)

Add several objects to the container. They are not necessarily added at the end.

virtual Float IMP::Model::evaluate	(	const RestraintsTemp &	restraints,
		bool	calc_derivs
	)			[virtual]

Evaluate a subset of the restraints.

The passed restraints must have been added to this model already.

Note:

Not all ScoreStates are updated during this call, only the ones which are needed to make sure the particles read by the restraints are up-to-date. The list of ScoreStates that needs to be updated for each restraint is currently recomputed when new score states are added, but not when the dependencies of Restraints or ScoreStates change. This can be fixed if requested.

Exceptions:

ModelException

if a Particle attribute value becomes invalid (NaN, infinite, etc.)

virtual Float IMP::Model::evaluate

(

bool

calc_derivs

)

[virtual]

Evaluate all of the restraints in the model and return the score.

Parameters:

[in]

calc_derivs

If true, also evaluate the first derivatives.

Returns:

The score.

Evaluation proceeds as follows:

• ScoreState::before_evaluate() is called on all ScoreStates
• Restraint::evaluate() is called on all Restraints
• ScoreState::after_evaluate() is called on all ScoreStates The sum of the Restraint::evaluate() return values is returned.

Exceptions:

ModelException

if a Particle attribute value becomes invalid (NaN, infinite etc.)

Restraint* IMP::Model::get_restraint

(

unsigned int

i

)

const

Get the object refered to by the index

Exceptions:

IndexException

in Python if the index is out of range

ScoreState* IMP::Model::get_score_state

(

unsigned int

i

)

const

Get the object refered to by the index

Exceptions:

IndexException

in Python if the index is out of range

void IMP::Model::remove_particle

(

Particle *

p

)

Remove the particle from this model.

Since particles are ref counted the object will still be valid until all references are removed, however attributes of removed particles cannot be changed or inspected.

Note:

It is an error to remove particles from the model during Restraint evaluation or ScoreState evaluation. It is OK to remove them during OptimizerState updates, although not all optimizers support this yet.

void IMP::Model::restore_particle

(

Particle *

p

)

Sometimes it is useful to put a particle back into a model.

When restoring the state of a Model, it is useful to be able to restore a particle back to the model it used to be part of.

void IMP::Model::set_is_incremental

(

bool

tf

)

Turn on or off incremental evaluation.

void IMP::Model::set_restraints

(

const Restraints &

ps

)

Set the contents of the container to ps removing all its current contents.

void IMP::Model::set_score_states

(

const ScoreStates &

ps

)

Set the contents of the container to ps removing all its current contents.

---

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

• Model.h
• __init__.py