IMP::Decorator Class Reference

---

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

• 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(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::VectorD<3>
• 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(), IMP_DECORATOR_ARRAY_DECL().

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

See also:

DecoratorWithTraits

Inheritance diagram for IMP::Decorator:

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 Decorator	setup_particle (Particle *p, extra_arguments)
static bool	particle_is_instance (Particle *p)
	Return true if the particle can be cast to the decorator.
Protected Member Functions
	Decorator (Particle *p)
int	compare (Particle *o) const

---

Constructor & Destructor Documentation

IMP::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::Decorator::Decorator

(

)

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

---

Member Function Documentation

Particle* IMP::Decorator::get_particle

(

)

const

Returns the particle decorated by this decorator.

static bool IMP::Decorator::particle_is_instance

(

Particle *

p

)

[static]

Return true if the particle can be cast to the decorator.

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);

Reimplemented in IMP::atom::Atom, IMP::atom::CHARMMAtom, IMP::atom::Charged, IMP::atom::Diffusion, IMP::atom::Hierarchy, IMP::atom::LennardJones, IMP::atom::Angle, IMP::atom::Dihedral, IMP::atom::Bond, IMP::atom::Bonded, IMP::core::XYZR, IMP::core::RigidBody, IMP::core::RigidMember, and IMP::example::ExampleDecorator.

static Decorator IMP::Decorator::setup_particle	(	Particle *	p,
		extra_arguments
	)		[static]

Add the needed attributes to the particle and initialize them with values taken from initial_values.

It is an error to call this twice on the same particle for the same type of decorator.

---

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

• Decorator.h