A decorator for a rigid body. More...

#include <IMP/core/rigid_bodies.h>

Inheritance diagram for IMP::core::RigidBody:

Detailed Description

A decorator for a rigid body.

A rigid body particle describes a set of particles, known as the members, which move rigidly together. The rigid body is represented as an algebra::ReferenceFrame3D coupled with local coordinates (RigidMember::get_internal_coordinates()) for the members expressed in that reference frame. The global coordinates of the members are accessed, as with other global coordinates, via the XYZ::get_coordinates().

Since the members are simply a set of particles which move together they don't (necessarily) define a shape. For example, the members of the rigid body made from a molecular hierarchy would include particles corresponding to intermediate levels of the hierarchy. As a result, methods that use rigid bodies usually should simply take the list of particles they are interested in and then check for rigid bodies internally.

The initial reference of the rigid body is computed from the coordinates, masses and radii of the particles passed to the constructor, based on diagonalizing the inertial tensor (which is not stored, currently).

RigidBodies can be nested (that is, a RigidBody can have another RigidBody as a member). This can be useful for organizational reasons as well as for accelerating computations since operations are affected by the total number of children contained in the rigid body being operated on. Examples of this include collision detection where if you have multiple representations of geometry at different resolutions it is faster to put each of them in a separate rigid body and then create one rigid body containing all of them.

It is often desirable to randomize the orientation of a rigid body:

 ## \example core/randomize_rigid_body.py
 # This fragment shows how to either perturb or set the orientation of a rigid
 # body randomly.
 
 import IMP.core
 import IMP.algebra
 import IMP
 
 m = IMP.kernel.Model()
 p = IMP.kernel.Particle(m)
 rbd = IMP.core.RigidBody.setup_particle(p, IMP.algebra.ReferenceFrame3D())
 translation = IMP.algebra.get_random_vector_in(
     IMP.algebra.get_unit_bounding_box_3d())
 
 # we don't yet have python code to generate a nearby rotation
 rotation = IMP.algebra.get_random_rotation_3d()
 transformation = IMP.algebra.Transformation3D(rotation, translation)
 # Option 1:
 # note, this overwrites the existing position
 rbd.set_reference_frame(IMP.algebra.ReferenceFrame3D(transformation))
 # Option 2:
 # perturb the existing transformation
 composed_tr = IMP.algebra.compose \
     (rbd.get_reference_frame().get_transformation_to(),
      transformation)
 rbd.set_reference_frame(IMP.algebra.ReferenceFrame3D(composed_tr))
 # Alternative to Option 2:
 IMP.core.transform(rbd, transformation)

Note: The maintenance of the invariant is done by an associated IMP::Constraint. As a result, the state is only guaranteed to be correct either during model evaluation, or immediately following model evaluation before any particles have been changed.

See Also: RigidMember; NonRigidMember; RigidBodyMover; RigidClosePairsFinder; RigidBodyDistancePairScore

Definition at line 75 of file rigid_bodies.h.

Public Member Functions
	RigidBody (const IMP::kernel::ParticleAdaptor &d)

	RigidBody (::IMP::kernel::Model *m,::IMP::kernel::ParticleIndex id)

void	add_member (kernel::ParticleIndexAdaptor p)

void	add_non_rigid_member (kernel::ParticleIndex pi)

const kernel::ParticleIndexes &	get_body_member_particle_indexes () const

algebra::Vector3D	get_coordinates () const
	Get the coordinates of the particle. More...

bool	get_coordinates_are_optimized () const

kernel::ParticleIndexes	get_member_indexes () const

const kernel::ParticleIndexes &	get_member_particle_indexes () const

RigidMembers	get_members () const

IMP::algebra::ReferenceFrame3D	get_reference_frame () const
	Get the reference frame for the local coordinates. More...

RigidMembers	get_rigid_members () const

algebra::VectorD< 4 >	get_rotational_derivatives () const
	Get the derivatives of the quaternion. More...

algebra::Vector3D	get_torque () const

void	normalize_rotation ()
	Normalize the quaternion. More...

void	set_coordinates_are_optimized (bool tf)

void	set_is_rigid_member (kernel::ParticleIndex pi, bool tf)

void	set_reference_frame (const IMP::algebra::ReferenceFrame3D &tr)
	Set the current reference frame. More...

void	set_reference_frame_from_members (const kernel::ParticleIndexes &members)

void	set_reference_frame_lazy (const IMP::algebra::ReferenceFrame3D &tr)
	Change the reference, delay updating the members until evaluate. More...

void	show (std::ostream &out=std::cout) const

void	update_members ()

Public Member Functions inherited from IMP::core::XYZ
	XYZ (::IMP::kernel::Model *m,::IMP::kernel::ParticleIndex id)

	XYZ (const IMP::kernel::ParticleAdaptor &d)

void	add_to_derivative (int i, Float v, DerivativeAccumulator &d)
	Add something to the derivative of the ith coordinate. More...

void	add_to_derivatives (const algebra::Vector3D &v, DerivativeAccumulator &d)
	Add something to the derivative of the coordinates. More...

Float	get_coordinate (int i) const
	Get the ith coordinate. More...

const algebra::Vector3D &	get_coordinates () const
	Convert it to a vector. More...

bool	get_coordinates_are_optimized () const
	Get whether the coordinates are optimized. More...

Float	get_derivative (int i) const
	Get the ith coordinate derivative. More...

algebra::Vector3D	get_derivatives () const
	Get the vector of derivatives. More...

algebra::Vector3D	get_vector_to (const XYZ &b) const
	Get the vector from this particle to another. More...

Float	get_x () const

Float	get_y () const

Float	get_z () const

void	set_coordinate (unsigned int i, Float v)
	set the ith coordinate More...

void	set_coordinates (const algebra::Vector3D &v)
	set all coordinates from a vector More...

void	set_coordinates_are_optimized (bool tf) const
	Set whether the coordinates are optimized. More...

void	set_x (Float t)

void	set_y (Float t)

void	set_z (Float t)

void	show (std::ostream &out=std::cout) const

Public Member Functions inherited from IMP::kernel::Decorator
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

Static Public Member Functions
static bool	get_is_setup (const IMP::kernel::ParticleAdaptor &p)

static bool	get_is_setup (kernel::Model *m, kernel::ParticleIndex pi)
	Return true if the particle is a rigid body. More...

static RigidBody	setup_particle (kernel::Model *m, ParticleIndex pi, kernel::ParticleIndexesAdaptor ps)

static RigidBody	setup_particle (IMP::kernel::ParticleAdaptor decorator, kernel::ParticleIndexesAdaptor ps)

static RigidBody	setup_particle (kernel::Model *m, ParticleIndex pi, algebra::ReferenceFrame3D rf)

static RigidBody	setup_particle (IMP::kernel::ParticleAdaptor decorator, algebra::ReferenceFrame3D rf)

static void	teardown_particle (RigidBody rb)
	Make the rigid body no longer rigid. More...

Static Public Member Functions inherited from IMP::core::XYZ
static FloatKey	get_coordinate_key (unsigned int i)

static bool	get_is_setup (const IMP::kernel::ParticleAdaptor &p)

static bool	get_is_setup (kernel::Model *m, kernel::ParticleIndex pi)

static const FloatKeys &	get_xyz_keys ()
	Get a vector containing the keys for x,y,z. More...

static XYZ	setup_particle (IMP::kernel::ParticleAdaptor decorator)

static XYZ	setup_particle (kernel::Model *m, ParticleIndex pi)

static XYZ	setup_particle (IMP::kernel::ParticleAdaptor decorator, algebra::Vector3D v)

static XYZ	setup_particle (kernel::Model *m, ParticleIndex pi, algebra::Vector3D v)

Additional Inherited Members
Protected Member Functions inherited from IMP::kernel::Decorator
	Decorator (Model *m, ParticleIndex pi)

	Decorator (ParticleAdaptor p)

Member Function Documentation

void IMP::core::RigidBody::add_member ( kernel::ParticleIndexAdaptor p )

Add a proper member that moves rigidly with this rigid body, properly handling rigid bodies and XYZ particles. Add p to the list of members. If p is a valid RigidBody, it is added as a rigid body member, otherwise it is added as a point member (for which the rotation is not tracked). By default, p is considered a strictly rigid member, in that its local coordinates are not expected to change independently.

See Also: add_non_rigid_member

void IMP::core::RigidBody::add_non_rigid_member ( kernel::ParticleIndex pi )

Add a non-rigid member, for which internal coordinates may change independently.

Note: Currently RigidBody non-rigid members are not handled properly.

const kernel::ParticleIndexes& IMP::core::RigidBody::get_body_member_particle_indexes ( ) const

Get all members that are themselves decorated as rigid bodies, as model particle indexes

Definition at line 140 of file rigid_bodies.h.

Here is the call graph for this function:

algebra::Vector3D IMP::core::RigidBody::get_coordinates ( ) const

Get the coordinates of the particle.

Definition at line 189 of file rigid_bodies.h.

Here is the call graph for this function:

bool IMP::core::RigidBody::get_coordinates_are_optimized ( ) const

Returns true if the rigid body coordinates are flagged as optimized for Optimizer objects

static bool IMP::core::RigidBody::get_is_setup	(	kernel::Model *	m,
		kernel::ParticleIndex	pi
	)

static

Return true if the particle is a rigid body.

Definition at line 183 of file rigid_bodies.h.

kernel::ParticleIndexes IMP::core::RigidBody::get_member_indexes ( ) const

Get the particle indexes of any member of this rigid body, regardless of whether it is itself a rigid body or not

Definition at line 153 of file rigid_bodies.h.

const kernel::ParticleIndexes& IMP::core::RigidBody::get_member_particle_indexes ( ) const

Returns a list of all members that are not themselves decorated as rigid bodies, in the form of particle indexes.

Definition at line 127 of file rigid_bodies.h.

Here is the call graph for this function:

RigidMembers IMP::core::RigidBody::get_members ( ) const

This method does not return non-rigid members.

Deprecated:: As of IMP release 2.2. See the IMP Deprecation Policy for more information about deprecation in IMP. Use get_rigid_members() instead.

Definition at line 118 of file rigid_bodies.h.

IMP::algebra::ReferenceFrame3D IMP::core::RigidBody::get_reference_frame ( ) const

Get the reference frame for the local coordinates.

Definition at line 192 of file rigid_bodies.h.

Here is the call graph for this function:

algebra::VectorD<4> IMP::core::RigidBody::get_rotational_derivatives ( ) const

Get the derivatives of the quaternion.

algebra::Vector3D IMP::core::RigidBody::get_torque ( ) const

The units are kCal/Mol/Radian

Definition at line 261 of file rigid_bodies.h.

Here is the call graph for this function:

void IMP::core::RigidBody::normalize_rotation ( )

Normalize the quaternion.

void IMP::core::RigidBody::set_coordinates_are_optimized ( bool tf )

Set whether the rigid body coordinates are flagged as optimized for Optimizer objects

void IMP::core::RigidBody::set_is_rigid_member	(	kernel::ParticleIndex	pi,
		bool	tf
	)

Set whether a particular member is flagged as a rigid member or as a non-rigid member. This affects the way the rigid body updates the coordinates and / or reference frame of its members.

void IMP::core::RigidBody::set_reference_frame ( const IMP::algebra::ReferenceFrame3D & tr )

Set the current reference frame.

All members of the rigid body will have their coordinates updated immediately.

See Also: IMP::core::transform(RigidBody,const algebra::Transformation3D&); set_reference_frame_lazy()

void IMP::core::RigidBody::set_reference_frame_from_members ( const kernel::ParticleIndexes & members )

Update the reference frame of the rigid body based on aligning the current global coordinates of the passed rigid body members onto their old local coordinates. Non-passed members are ignored.

This method is useful for updating the rigid body after new global coordinates were loaded for the members. The members are passed explicitly since, typically, some are desired to just move along with the newly loaded rigid body.

Note: This requires at least three members that are not colinear to work.

void IMP::core::RigidBody::set_reference_frame_lazy ( const IMP::algebra::ReferenceFrame3D & tr )

Change the reference, delay updating the members until evaluate.

See Also: set_reference_frame()

static RigidBody IMP::core::RigidBody::setup_particle	(	IMP::kernel::ParticleAdaptor	decorator,
		kernel::ParticleIndexesAdaptor	ps
	)

static

See Also: setup_particle(m, pi, ps )

Definition at line 168 of file rigid_bodies.h.

static RigidBody IMP::core::RigidBody::setup_particle	(	kernel::Model *	m,
		ParticleIndex	pi,
		kernel::ParticleIndexesAdaptor	ps
	)

static

Create a rigid body for pi with the particle indexes ps as its members. The coordinates of pi are set to the center of mass of ps and the rotation of its reference frame is based on the diagonalized inertia tensor of ps.

Note: If size(ps)=1, then its reference frame is copied if it is a rigid body, or its rotation is set to identity if it is not a rigid body.Setup the particle so that it can be used with this decorator

Definition at line 168 of file rigid_bodies.h.

static RigidBody IMP::core::RigidBody::setup_particle	(	kernel::Model *	m,
		ParticleIndex	pi,
		algebra::ReferenceFrame3D	rf
	)

static

Create a rigid body with the passed reference frame as its initial position.Setup the particle so that it can be used with this decorator

Definition at line 174 of file rigid_bodies.h.

static RigidBody IMP::core::RigidBody::setup_particle	(	IMP::kernel::ParticleAdaptor	decorator,
		algebra::ReferenceFrame3D	rf
	)

static

See Also: setup_particle(m, pi, rf )

Definition at line 174 of file rigid_bodies.h.

static void IMP::core::RigidBody::teardown_particle ( RigidBody rb )

static

Make the rigid body no longer rigid.

void IMP::core::RigidBody::update_members ( )

Update the global coordinates of the members based on their local coordinates and this rigid body's reference frame

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

rigid_bodies.h

Detailed Description

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Member Function Documentation