Detailed Description

Interface to specialized Particle types (e.g. atoms)

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::Model::add_attribute(), IMP::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::Model* and IMP::ParticleIndex pair, an IMP::Particle* 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 call decorates the particle and also 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 pi 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” in some places and “X” in 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.

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

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

A decorator can be cast to a IMP::Particle* in C++. In Python Decorator objects can be used anywhere where Particle or ParticleIndex objects are expected (use the get_particle() method to get the Particle itself).

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 118 of file Decorator.h.

Public Member Functions
bool	get_is_valid () const
	Returns true if constructed with a non-default constructor. More...

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::Decorator::get_is_valid ( ) const

Returns true if constructed 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 200 of file Decorator.h.

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

Returns the Model containing the particle.

Definition at line 191 of file Decorator.h.

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

Returns the particle decorated by this decorator.

Definition at line 171 of file Decorator.h.

ParticleIndex IMP::Decorator::get_particle_index ( ) const

Returns the particle index decorated by this decorator.

Definition at line 188 of file Decorator.h.

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

Decorator.h

Detailed Description

Public Member Functions

Protected Member Functions

Member Function Documentation