IMP::kernel::Decorator Class Reference

#include <IMP/kernel/Decorator.h>

Inheritance diagram for IMP::kernel::Decorator:

Public Member Functions
ParticleIndex	get_particle_index () const

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

Methods provided by the Decorator class
The following methods are provided by the Decorator class.
Particle *	get_particle () const
Model *	get_model () const
	Returns the Model containing the particle.

Methods that all decorators must have
All decorators must have the following methods. Decorators which are parameterized (for example IMP::core::XYZR) take an (optional) extra parameter after the Particle in setup_particle(), and particle_is_instance(). Note these are not actually methods of the Decorator class itself.
	Decorator (Particle *p)
	Decorator ()
static bool	particle_is_instance (Particle *p)
	Return true if the particle can be cast to the decorator. More...

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::Particle::add_attribute(), IMP::Particle::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

Dealing with decorators and particles has two main parts

1. setting up the particle to be used with that decorator
2. 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(p, 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(p)

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

if IMP.core.XYZ.particle_is_instance(p):

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(), IMP_DECORATOR_WITH_TRAITS(), IMP_DECORATOR_GET().

Advanced:

Lists of decorators are reference counted even though the individual decorators are not. For more efficiency you can use the non-reference counted version, IMP::core::XYZs instead. This should only be done when it is known to be safe. If you can't figure out that it is, don't do it.

A decorator can be cast to a IMP::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 115 of file kernel/Decorator.h.

Constructor & Destructor Documentation

IMP::kernel::Decorator::Decorator

(

Particle *

p

)

Create an instance of the Decorator from the particle that has already been set up. The particle must have been set up already (eg particle_is_instance(p) must be true), but this is not necessarily checked.

IMP::kernel::Decorator::Decorator

(

)

The default constructor must be defined and create a nullptr decorator, analogous to a nullptr pointer in C++ or a None object in Python.

Member Function Documentation

Particle* IMP::kernel::Decorator::get_particle

(

)

const

Returns the particle decorated by this decorator. Returns the particle decorated by this decorator.

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

static bool IMP::kernel::Decorator::particle_is_instance ( Particle *  p )

static

That is, if particle_is_instance() returns true, then it is legal to construct an instance of the decorator with that particle. If not, setup_particle() must be called first.

IMP::Particle *p = new IMP::Particle(m);
// it is false
std::cout << IMP::core::XYZ::particle_is_instance(p) << std::endl;
// As a result this is an error
IMP::core::XYZ d(p);
// now set it up
IMP::core::XYZ(p);
// now it is true
std::cout << IMP::core::XYZ::particle_is_instance(p) << std::endl;
// and now this code is OK
IMP::core::XYZ d(p);

---

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

• kernel/Decorator.h