IMP logo
IMP Reference Guide  2.17.0
The Integrative Modeling Platform
IMP::Model Class Reference

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

#include "IMP/Model.h"

+ Inheritance diagram for IMP::Model:

Detailed Description

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

Proxy of C++ IMP::Model class.

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

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.

Examples:
atom/dope_and_excluded_volume.cpp, and core/simple.cpp.

Definition at line 73 of file Model.h.

Public Member Functions

 Model (std::string name="Model %1%")
 Construct an empty model. More...
 
ParticleIndex add_particle (std::string name)
 Add particle to the model. More...
 
void add_undecorator (ParticleIndex pi, Undecorator *d)
 Add the passed Undecorator to the particle. More...
 
void clear_particle_caches (ParticleIndex pi)
 Clear all the cache attributes of a given particle. More...
 
unsigned get_dependencies_updated ()
 Get the model age when ModelObject dependencies were last changed, or 0. More...
 
def get_derivatives_numpy
 Get the model's attribute derivatives array for FloatKey k as a NumPy array. More...
 
def get_floats_numpy
 Get the model's attribute array for FloatKey k as a NumPy array. More...
 
bool get_has_particle (ParticleIndex p) const
 Check whether a given particle index exists. More...
 
def get_ints_numpy
 Get the model's attribute array for IntKey k as a NumPy array. More...
 
ModelObjectsTemp get_model_objects () const
 Get all the ModelObjects associated with this Model. More...
 
Particleget_particle (ParticleIndex p) const
 Get the particle from an index. More...
 
ParticleIndexes get_particle_indexes ()
 Get all particle indexes. More...
 
std::string get_particle_name (ParticleIndex pi)
 Get the name of a particle. More...
 
unsigned get_particles_size () const
 Get an upper bound on the number of particles in the Model. More...
 
def get_sphere_derivatives_numpy
 Get the model's XYZR attribute derivatives arrays as NumPy arrays. More...
 
def get_spheres_numpy
 Get the model's XYZR attribute arrays as NumPy arrays. More...
 
virtual std::string get_type_name () const override
 
virtual ::IMP::VersionInfo get_version_info () const override
 Get information about the module and version of the object. More...
 
void remove_particle (ParticleIndex pi)
 Remove a particle from the Model. More...
 
void restore_dependencies ()
 Restore ModelObject dependencies to previous restore point. More...
 
void save_dependencies ()
 Mark a 'restore point' for ModelObject dependencies. More...
 
void update ()
 Sometimes it is useful to be able to make sure the model is up to date. More...
 
- Public Member Functions inherited from IMP::Object
virtual void clear_caches ()
 
CheckLevel get_check_level () const
 
LogLevel get_log_level () const
 
void set_check_level (CheckLevel l)
 
void set_log_level (LogLevel l)
 Set the logging level used in this object. More...
 
void set_was_used (bool tf) const
 
void show (std::ostream &out=std::cout) const
 
const std::string & get_name () const
 
void set_name (std::string name)
 

States

ScoreStates maintain invariants in the Model (see ScoreState for more information.)

ScoreStates do not need to be explictly added to the Model, but they can be if desired in order to keep them alive as long as the model is alive.

Note
Familiarity with these methods is not required to use IMP.
void remove_score_state (ScoreState *d)
 
void remove_score_states (const ScoreStates &d)
 
void set_score_states (const ScoreStates &ps)
 
void set_score_states_order (const ScoreStates &objs)
 
unsigned int add_score_state (ScoreState *obj)
 
void add_score_states (const ScoreStates &objs)
 
void clear_score_states ()
 
unsigned int get_number_of_score_states () const
 
bool get_has_score_states ()
 
ScoreStateget_score_state (unsigned int i) const
 
ScoreStates get_score_states () const
 
void reserve_score_states (unsigned int sz)
 

Accessing attributes

All the attribute data associated with each Particle are stored in the Model. For each type of attribute, there are the methods detailed below (where, eg, TypeKey is FloatKey or StringKey)

void add_attribute (TypeKey attribute_key, ParticleIndex particle, Type value)
 add particle atribute with the specied key and initial value More...
 
void remove_attribute (TypeKey attribute_key, ParticleIndex particle)
 remove particle attribute with the specied key More...
 
bool get_has_attribute (TypeKey attribute_key, ParticleIndex particle) const
 return true if particle has attribute with the specified key More...
 
void set_attribute (TypeKey attribute_key, ParticleIndex particle, Type value)
 set the value of particle attribute with the specified key More...
 
Type get_attribute (TypeKey attribute_key, ParticleIndex particle)
 get the value of the particle attribute with the specified key More...
 
void add_cache_attribute (TypeKey attribute_key, ParticleIndex particle, Type value)
 
void set_is_optimized (TypeKey attribute_key, ParticleIndex particle, bool true_or_false)
 

Storing data in the model

One can store data associated with the model. This is used, for example, to keep a central ScoreState to normalize rigid body rotational variables.

void add_data (ModelKey mk, Object *o)
 Store a piece of data in the model referenced by the key. More...
 
Objectget_data (ModelKey mk) const
 Get back some data stored in the model. More...
 
void remove_data (ModelKey mk)
 Remove data stored in the model. More...
 
bool get_has_data (ModelKey mk) const
 Check if the model has a certain piece of data attached. More...
 

Model triggers

Triggers can be used to track when to clear and rebuild caches of derived model properties. For example, a Restraint may restrain two particles as a function of the number of chemical bonds between them. To speed up this restraint, the bond graph can be cached; however, this graph needs to be rebuilt if bonds are created or removed. This can be achieved by checking that the model time (see get_age()) of the cache matches the time when the 'bond added/removed' Trigger was last updated (see get_trigger_last_updated()), either when the Restraint is evaluated or in an associated ScoreState.

Triggers are intended for events that are rare during a typical optimization. Triggers can be created by any IMP module in either C++ or Python by creating a new TriggerKey, much as model attributes are handled. To avoid name collisions, it is recommended to prepend the module and/or class name to the trigger, e.g. "atom.Bond.changed".

For an example, see IMP::score_functor::OrientedSoap, which uses a cache built from the molecular hierarchy, which is cleared when the IMP::core::Hierarchy::get_changed_key() trigger is updated.

unsigned get_age ()
 Get the current 'model time'. More...
 
unsigned get_trigger_last_updated (TriggerKey tk)
 Get the time when the given trigger was last updated, or 0. More...
 
void set_trigger_updated (TriggerKey tk)
 Update the given trigger. More...
 

Additional Inherited Members

- Protected Member Functions inherited from IMP::Object
 Object (std::string name)
 Construct an object with the given name. More...
 
virtual void do_destroy ()
 

Constructor & Destructor Documentation

IMP::Model::Model ( std::string  name = "Model %1%")

Construct an empty model.

Member Function Documentation

void IMP::Model::add_attribute ( TypeKey  attribute_key,
ParticleIndex  particle,
Type  value 
)

add particle atribute with the specied key and initial value

Precondition
get_has_attribute(attribute_key, particle) is false
void IMP::Model::add_cache_attribute ( TypeKey  attribute_key,
ParticleIndex  particle,
Type  value 
)

Cache attributes, unlike normal attributes, can be added during evaluation. They are also cleared by the clear_cache_attributes() method. Cache attributes should be used when one is adding data to a particle to aid scoring (eg cache the rigid body collision acceleration structure).

When some pertinent aspect of the particle changes, the clear method should be called (yes, this is a bit vague). Examples where it should be cleared include changing the set of members of a core::RigidBody or their coordinates, changing the members of an atom::Hierarchy.

void IMP::Model::add_data ( ModelKey  mk,
Object o 
)

Store a piece of data in the model referenced by the key.

ParticleIndex IMP::Model::add_particle ( std::string  name)

Add particle to the model.

Examples:
atom/dope_and_excluded_volume.cpp.
void IMP::Model::add_undecorator ( ParticleIndex  pi,
Undecorator d 
)

Add the passed Undecorator to the particle.

void IMP::Model::clear_particle_caches ( ParticleIndex  pi)

Clear all the cache attributes of a given particle.

unsigned IMP::Model::get_age ( )

Get the current 'model time'.

This is a number 1 or more that tracks the 'age' of the model; it is incremented every time before_evaluate() is called. It may wrap (and so should not be assumed to always increase) but will never be 0.

Definition at line 433 of file Model.h.

Type IMP::Model::get_attribute ( TypeKey  attribute_key,
ParticleIndex  particle 
)

get the value of the particle attribute with the specified key

Precondition
get_has_attribute(attribute_key, particle) is true
Object* IMP::Model::get_data ( ModelKey  mk) const

Get back some data stored in the model.

unsigned IMP::Model::get_dependencies_updated ( )

Get the model age when ModelObject dependencies were last changed, or 0.

This gives the Model age (see get_age()) when Particles, Restraints, or ScoreStates were last added or removed. It is typically used to help maintain caches that depend on the model's dependency graph.

Definition at line 459 of file Model.h.

def IMP.Model.get_derivatives_numpy (   self,
  k 
)

Get the model's attribute derivatives array for FloatKey k as a NumPy array.

See Model::get_ints_numpy() for more details.

Definition at line 6198 of file __init__.py.

def IMP.Model.get_floats_numpy (   self,
  k 
)

Get the model's attribute array for FloatKey k as a NumPy array.

See Model::get_ints_numpy() for more details.

Definition at line 6193 of file __init__.py.

bool IMP::Model::get_has_attribute ( TypeKey  attribute_key,
ParticleIndex  particle 
) const

return true if particle has attribute with the specified key

bool IMP::Model::get_has_data ( ModelKey  mk) const

Check if the model has a certain piece of data attached.

bool IMP::Model::get_has_particle ( ParticleIndex  p) const

Check whether a given particle index exists.

Definition at line 372 of file Model.h.

def IMP.Model.get_ints_numpy (   self,
  k 
)

Get the model's attribute array for IntKey k as a NumPy array.

The array is indexed by ParticleIndex; particles that don't have this attribute will either be off the end of the array or will have the value INT_MAX. This is a NumPy view that shares memory with the Model. Thus, any changes to values in this list will be reflected in the Model. Also, if the Model attribute array moves in memory (e.g. if particles or attributes are added) this array will be invalidated, so it is unsafe to keep it around long term.

Definition at line 6180 of file __init__.py.

ModelObjectsTemp IMP::Model::get_model_objects ( ) const

Get all the ModelObjects associated with this Model.

Particle* IMP::Model::get_particle ( ParticleIndex  p) const

Get the particle from an index.

Definition at line 366 of file Model.h.

ParticleIndexes IMP::Model::get_particle_indexes ( )

Get all particle indexes.

std::string IMP::Model::get_particle_name ( ParticleIndex  pi)

Get the name of a particle.

unsigned IMP::Model::get_particles_size ( ) const

Get an upper bound on the number of particles in the Model.

This value is guaranteed to be at least the number of particles in the model (there may be fewer particles if any have been removed) and every ParticleIndex will be smaller than this value.

Definition at line 505 of file Model.h.

def IMP.Model.get_sphere_derivatives_numpy (   self)

Get the model's XYZR attribute derivatives arrays as NumPy arrays.

See Model::get_ints_numpy() for more details.

Definition at line 6211 of file __init__.py.

def IMP.Model.get_spheres_numpy (   self)

Get the model's XYZR attribute arrays as NumPy arrays.

The attribute arrays for Cartesian coordinates and radii are stored separately from those for other FloatKeys. This function returns a tuple of two NumPy arrays, the first of coordinates and the second of radii. See Model::get_ints_numpy() for more details.

Definition at line 6205 of file __init__.py.

unsigned IMP::Model::get_trigger_last_updated ( TriggerKey  tk)

Get the time when the given trigger was last updated, or 0.

Return the 'model time' (as given by get_age()) when the given trigger was last updated on this model, or 0 if never.

Definition at line 438 of file Model.h.

virtual ::IMP::VersionInfo IMP::Model::get_version_info ( ) const
overridevirtual

Get information about the module and version of the object.

Reimplemented from IMP::Object.

Definition at line 507 of file Model.h.

void IMP::Model::remove_attribute ( TypeKey  attribute_key,
ParticleIndex  particle 
)

remove particle attribute with the specied key

Precondition
get_has_attribute(attribute_key, particle) is true
void IMP::Model::remove_data ( ModelKey  mk)

Remove data stored in the model.

void IMP::Model::remove_particle ( ParticleIndex  pi)

Remove a particle from the Model.

The particle will then be inactive and cannot be used for anything and all data stored in the particle is lost.

void IMP::Model::restore_dependencies ( )

Restore ModelObject dependencies to previous restore point.

This method, when paired with save_dependencies(), can be used to avoid triggering a model dependency update due to a temporary change in the model dependency graph, for example due to adding a temporary restraint, evaluating it, then removing that same restraint. It should only be called in cases where it is known that the dependency graph is the same as when save_dependencies() was called (this is only checked in debug mode). Save/restore call pairs cannot be nested, although it is OK to skip the call to restore_dependencies(), e.g. if an exception occurs.

See Also
get_dependencies_updated()
save_dependencies()

Definition at line 486 of file Model.h.

void IMP::Model::save_dependencies ( )

Mark a 'restore point' for ModelObject dependencies.

See Also
restore_dependencies()

Definition at line 463 of file Model.h.

void IMP::Model::set_attribute ( TypeKey  attribute_key,
ParticleIndex  particle,
Type  value 
)

set the value of particle attribute with the specified key

Precondition
get_has_attribute(attribute_key, particle) is true
void IMP::Model::set_is_optimized ( TypeKey  attribute_key,
ParticleIndex  particle,
bool  true_or_false 
)

Optimized attributes are the parameters of the model that are allowed to be modified by samplers and optimizers

void IMP::Model::set_trigger_updated ( TriggerKey  tk)

Update the given trigger.

Definition at line 447 of file Model.h.

void IMP::Model::update ( )

Sometimes it is useful to be able to make sure the model is up to date.

This method updates all the state but does not necessarily compute the score. Use this to make sure that your containers and rigid bodies are up to date.


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