Detailed Description

Representation of the structure in IMP is via a collection of Particle objects. However, since particles are general purpose, they provide a basic set of tools for managing the data (e.g. IMP::kernel::Model::add_attribute(), IMP::kernel::Model::get_value() etc). Decorators wrap (or “decorate”) particles to provide a much richer interface. For example, most particles have Cartesian coordinates. The class IMP::core::XYZ decorates such a particle to provide functions to get and set the Cartesian coordinates as well as compute distances between particles.

d0= IMP.core.XYZ(p0)
d1= IMP.core.XYZ(p1)
print IMP.core.distance(d0,d1)
print d0.get_coordinates()

Decorator basics

Note: The get_is_setup() and setup_particle() functions mentioned below can take any of either an IMP::kernel::Model* and IMP::kernel::ParticleIndex pair, an IMP::kernel::Paricle* or another decorator to identify the particle. We use various of those below.

Dealing with decorators and particles has two main parts

setting up the particle to be used with that decorator
decorating the particle.

To set up a particle to be used with the IMP::core::XYZ decorator we do

d0= IMP.core.XYZ.setup_particle(m, pi, IMP.algebra.Vector3D(0,2,3))

The method calls also decorates the particle and returns the decorator which can now be used to manipulate the particle. For example we can access the coordinates (0,2,3) by doing

print d0.get_coordinates()

We now say the particle is an XYZ particle. If that particle is encountered later when we do not have the existing decorator available, we can decorate it again (since it is already set up) by doing

d1= IMP.core.XYZ(m, pi)

If you do not know if p has been set up for the XYZ decorator, you can ask with

if IMP.core.XYZ.get_is_setup(m, pi):

More abstractly, decorators can be used to

maintain invariants: e.g. an IMP::atom::Bond particle always connects two other particles, both of which are IMP::atom::Bonded particles.
add functionality: e.g. you can get the coordinates as an IMP::algebra::Vector3D
provide uniform names for attributes: so you do not use “x” some places and “X” other places

To see a list of all available decorators and to see what functions all decorators have, look at the list of classes which inherit from IMP::Decorator, below.

See the IMP::example::ExampleDecorator example for how to implement a simple decorator.

Note: Decorator objects are ordered based on the address of the wrapped particle. Like pointers, they are logical values so can be in if statements.

Implementors: Developers who wish to implement a Decorator should inherit from this class and use the IMP_DECORATOR() macro to help define the needed functions. IMP::example::ExampleDecorator provides an example to start from.

For efficiency reasons attribute keys should always be created lazily (at the time of the first use), and not be created as static variables. The reason for this is that initialized attribute keys result in space being allocated in decorators, even before they are used.

Implementors should consult IMP::example::ExampleDecorator, IMP_DECORATOR_METHODS(), IMP_DECORATOR_WITH_TRAITS_METHODS(), IMP_DECORATOR_GET().

A decorator can be cast to a IMP::kernel::Particle* in C++. You have to use the Decorator::get_particle() function in Python.

Note: It is undefined behavior to use a decorator constructed on a particle that is no longer part of a model. Since constructing decorators is very cheap, you probably should not store decorators, and then would not have this problem.

See example::ExampleDecorator to see what a minimal decorator looks like.

Definition at line 116 of file kernel/Decorator.h.

Public Member Functions
bool	get_is_valid () const

Model *	get_model () const
	Returns the Model containing the particle. More...

Particle *	get_particle () const
	Returns the particle decorated by this decorator. More...

ParticleIndex	get_particle_index () const
	Returns the particle index decorated by this decorator. More...

	operator Particle * () const

	operator ParticleIndex () const

Particle *	operator-> () const

Protected Member Functions
	Decorator (Model *m, ParticleIndex pi)

	Decorator (ParticleAdaptor p)

Member Function Documentation

bool IMP::kernel::Decorator::get_is_valid ( ) const

Returns true if the decorator was constructued with a non-default constructor.

Note: It is guaranteed that this is a very fast method. However, this method might return false if the particle itself was invalidated after construction - use check_particle() in that case.

Definition at line 199 of file kernel/Decorator.h.

Model* IMP::kernel::Decorator::get_model ( ) const

Returns the Model containing the particle.

Definition at line 189 of file kernel/Decorator.h.

Particle* IMP::kernel::Decorator::get_particle ( ) const

Returns the particle decorated by this decorator.

Definition at line 169 of file kernel/Decorator.h.

ParticleIndex IMP::kernel::Decorator::get_particle_index ( ) const

Returns the particle index decorated by this decorator.

Definition at line 186 of file kernel/Decorator.h.

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

kernel/Decorator.h

Detailed Description

Public Member Functions

Protected Member Functions

Member Function Documentation