IMP logo
IMP Reference Guide  2.6.2
The Integrative Modeling Platform
IMP::core::RigidBody Class Reference

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:

1 ## \example core/randomize_rigid_body.py
2 # This fragment shows how to either perturb or set the orientation of a rigid
3 # body randomly.
4 
5 import IMP.core
6 import IMP.algebra
7 import IMP
8 import sys
9 
10 IMP.setup_from_argv(sys.argv, "randomize rigid body")
11 
12 m = IMP.Model()
13 p = IMP.Particle(m)
16  IMP.algebra.get_unit_bounding_box_3d())
17 
18 # we don't yet have python code to generate a nearby rotation
20 transformation = IMP.algebra.Transformation3D(rotation, translation)
21 # Option 1:
22 # note, this overwrites the existing position
23 rbd.set_reference_frame(IMP.algebra.ReferenceFrame3D(transformation))
24 # Option 2:
25 # perturb the existing transformation
26 composed_tr = IMP.algebra.compose \
27  (rbd.get_reference_frame().get_transformation_to(),
28  transformation)
29 rbd.set_reference_frame(IMP.algebra.ReferenceFrame3D(composed_tr))
30 # Alternative to Option 2:
31 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 (::IMP::Model *m,::IMP::ParticleIndex id)
 
 RigidBody (const IMP::ParticleAdaptor &d)
 
void add_member (ParticleIndexAdaptor p)
 
void add_non_rigid_member (ParticleIndexAdaptor p)
 
const ParticleIndexesget_body_member_particle_indexes () const
 
algebra::Vector3D get_coordinates () const
 Get the coordinates of the particle. More...
 
bool get_coordinates_are_optimized () const
 
ParticleIndexes get_member_indexes () const
 
const ParticleIndexesget_member_particle_indexes () 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 (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 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::Model *m,::IMP::ParticleIndex id)
 
 XYZ (const IMP::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::Vector3Dget_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::Decorator
bool get_is_valid () const
 Returns true if constructed with a non-default constructor. More...
 
Modelget_model () const
 Returns the Model containing the particle. More...
 
Particleget_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
 
Particleoperator-> () const
 

Static Public Member Functions

static bool get_is_setup (const IMP::ParticleAdaptor &p)
 
static bool get_is_setup (Model *m, ParticleIndex pi)
 Return true if the particle is a rigid body. More...
 
static RigidBody setup_particle (Model *m, ParticleIndex pi, ParticleIndexesAdaptor ps)
 
static RigidBody setup_particle (IMP::ParticleAdaptor decorator, ParticleIndexesAdaptor ps)
 
static RigidBody setup_particle (Model *m, ParticleIndex pi, algebra::ReferenceFrame3D rf)
 
static RigidBody setup_particle (IMP::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::ParticleAdaptor &p)
 
static bool get_is_setup (Model *m, ParticleIndex pi)
 
static const FloatKeysget_xyz_keys ()
 Get a vector containing the keys for x,y,z. More...
 
static XYZ setup_particle (IMP::ParticleAdaptor decorator)
 
static XYZ setup_particle (Model *m, ParticleIndex pi)
 
static XYZ setup_particle (IMP::ParticleAdaptor decorator, algebra::Vector3D v)
 
static XYZ setup_particle (Model *m, ParticleIndex pi, algebra::Vector3D v)
 

Additional Inherited Members

- Protected Member Functions inherited from IMP::Decorator
 Decorator (Model *m, ParticleIndex pi)
 
 Decorator (ParticleAdaptor p)
 

Member Function Documentation

void IMP::core::RigidBody::add_member ( 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 ( ParticleIndexAdaptor  p)

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

Note
Currently RigidBody non-rigid members are not handled properly.
const 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 130 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 179 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 ( Model m,
ParticleIndex  pi 
)
static

Return true if the particle is a rigid body.

Definition at line 173 of file rigid_bodies.h.

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 143 of file rigid_bodies.h.

const 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 117 of file rigid_bodies.h.

+ Here is the call graph for this function:

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

Get the reference frame for the local coordinates.

Definition at line 182 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 251 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 ( 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 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 ( Model m,
ParticleIndex  pi,
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 158 of file rigid_bodies.h.

static RigidBody IMP::core::RigidBody::setup_particle ( IMP::ParticleAdaptor  decorator,
ParticleIndexesAdaptor  ps 
)
static
See Also
setup_particle(m, pi, ps )

Definition at line 158 of file rigid_bodies.h.

static RigidBody IMP::core::RigidBody::setup_particle ( IMP::ParticleAdaptor  decorator,
algebra::ReferenceFrame3D  rf 
)
static
See Also
setup_particle(m, pi, rf )

Definition at line 164 of file rigid_bodies.h.

static RigidBody IMP::core::RigidBody::setup_particle ( 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 164 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: