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

The rigid body radius is the farthest point of any of its members from the origin of its reference frame. For rigid body members, this takes into account the radius of the member.

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
 import sys
 
 IMP.setup_from_argv(sys.argv, "randomize rigid body")
 
 m = IMP.Model()
 p = IMP.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 82 of file rigid_bodies.h.

Public Member Functions
	RigidBody (::IMP::Model *m,::IMP::ParticleIndex id)

	RigidBody (const IMP::ParticleAdaptor &d)

	RigidBody (const RigidBody &)=default

void	add_member (ParticleIndexAdaptor p)

void	add_non_rigid_member (ParticleIndexAdaptor p)

void	add_to_derivatives (const algebra::Vector3D &local_derivative, const algebra::Vector3D &local_location, DerivativeAccumulator &da)

void	add_to_derivatives (const algebra::Vector3D &local_derivative, const algebra::Vector3D &global_derivative, const algebra::Vector3D &local_location, const algebra::Rotation3D &rot_local_to_global, DerivativeAccumulator &da)

void	add_to_rotational_derivatives (const algebra::Vector4D &other_qderiv, const algebra::Rotation3D &rot_other_to_local, const algebra::Rotation3D &rot_local_to_global, DerivativeAccumulator &da)

void	add_to_rotational_derivatives (const algebra::Vector4D &qderiv, DerivativeAccumulator &da)

void	add_to_torque (const algebra::Vector3D &torque_local, DerivativeAccumulator &da)

const ParticleIndexes &	get_body_member_particle_indexes () const

algebra::Vector3D	get_coordinates () const

bool	get_coordinates_are_optimized () const

ParticleIndexes	get_member_indexes () const

const ParticleIndexes &	get_member_particle_indexes () const

IMP::algebra::ReferenceFrame3D	get_reference_frame () const

RigidMembers	get_rigid_members () const

IMP::algebra::Rotation3D	get_rotation () 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...

RigidBody &	operator= (const RigidBody &)=default

void	pull_back_body_member_adjoints (ParticleIndex pi, DerivativeAccumulator &da)
	Pull back global adjoints from member that is also a rigid body. More...

void	pull_back_body_member_adjoints (ParticleIndex pi, const algebra::Transformation3D &TA, algebra::Transformation3D &TB, algebra::Transformation3DAdjoint &DTC, algebra::Transformation3DAdjoint &DTA, algebra::Transformation3DAdjoint &DTB, algebra::Vector3D &betatorque, DerivativeAccumulator &da)

void	pull_back_member_adjoints (ParticleIndex pi, DerivativeAccumulator &da)
	Pull back global adjoints from member that is a point. More...

void	pull_back_member_adjoints (ParticleIndex pi, const algebra::Transformation3D &T, algebra::Vector3D &x, algebra::Vector3D &Dy, algebra::Vector3D &Dx, algebra::Transformation3DAdjoint &DT, algebra::Vector3D &xtorque, DerivativeAccumulator &da)

void	pull_back_members_adjoints (DerivativeAccumulator &da)
	Pull back global adjoints from members. More...

void	remove_member (ParticleIndexAdaptor p)
	Remove the member from this rigid body. 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)

void	add_to_derivatives (const algebra::Vector3D &v, DerivativeAccumulator &d)
	Add the vector v to the derivative vector of the x,y,z 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

algebra::Vector3D	get_derivatives () const
	Get the vector of derivatives accumulated by add_to_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...

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::ParticleAdaptor &p)

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

static FloatKeys	get_rotation_keys ()
	Get keys for rotation quaternion. More...

static RigidBody	setup_particle (IMP::ParticleAdaptor pa, ParticleIndexesAdaptor ps)

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

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

static RigidBody	setup_particle (Model *m, ParticleIndex pi, 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 FloatKeys &	get_xyz_keys ()
	Get a vector containing the keys for x,y,z. More...

static XYZ	setup_particle (IMP::ParticleAdaptor pa)

static XYZ	setup_particle (Model *m, ParticleIndex pi)

static XYZ	setup_particle (IMP::ParticleAdaptor pa, 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.

The radius of the rigid body is updated to reflect the new member.

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.

void IMP::core::RigidBody::add_to_derivatives	(	const algebra::Vector3D &	local_derivative,
		const algebra::Vector3D &	local_location,
		DerivativeAccumulator &	da
	)

Update the translational and rotational derivatives on the rigid body center of mass, using the Cartesian derivative vector at a specified location (the point where the force is being applied).

Updates both the quaternion derivatives and the torque.

Parameters

local_derivative	The derivative vector in local rigid body coordinates
local_location	The location where the derivative is taken in local rigid body coordinates
da	Accumulates the output derivative over the rigid body center of mass (translation and rotation torque, quaternion)

void IMP::core::RigidBody::add_to_derivatives	(	const algebra::Vector3D &	local_derivative,
		const algebra::Vector3D &	global_derivative,
		const algebra::Vector3D &	local_location,
		const algebra::Rotation3D &	rot_local_to_global,
		DerivativeAccumulator &	da
	)

Faster version of the above, if all is cached.

Parameters

local_derivative	The derivative vector in local rigid body coordinates
global_derivative	The derivative vector in global coordinates
local_location	The location where the derivative is taken in local rigid body coordinates
rot_local_to_global	Rotation matrix from local rigid body to global coordinates
da	Accumulates the output derivative over the rigid body center of mass (translation and rotation torque, quaternion)

void IMP::core::RigidBody::add_to_rotational_derivatives	(	const algebra::Vector4D &	other_qderiv,
		const algebra::Rotation3D &	rot_other_to_local,
		const algebra::Rotation3D &	rot_local_to_global,
		DerivativeAccumulator &	da
	)

Update the rotational derivatives from another body specified by the rotation from the other body's local coordinates to this body's local coordinates. The provided quaternion derivative on the other body are in the reference frame of the other body.

Updates only quaternion derivatives.

Parameters

other_qderiv	The derivative on the quaternion taking the other body's local coordinates to global.
rot_other_to_local	Rotation taking the local coordinates of the other body to this body's local coordinates.
rot_local_to_global	Rotation taking this rigid body's local coordinates to global coordinates.
da	Accumulates the output derivatives.

void IMP::core::RigidBody::add_to_rotational_derivatives	(	const algebra::Vector4D &	qderiv,
		DerivativeAccumulator &	da
	)

Add to quaternion derivative of this rigid body Note that this method does not update the torque.

Parameters

qderiv	Derivative wrt to quaternion taking local coordinates to global.
da	Object for accumulating derivatives

void IMP::core::RigidBody::add_to_torque	(	const algebra::Vector3D &	torque_local,
		DerivativeAccumulator &	da
	)

Add torque to derivative table of this rigid body Note that this method does not update the quaternion derivatives, so should be used by optimizers that rely on torque only (e.g. BrownianDynamics)

Parameters

torque_local	Torque vector in local reference frame, in units of kCal/Mol/Radian
da	Object for accumulating derivatives

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 152 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 (= translation from local to global rigid body coordinates)

Definition at line 204 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 197 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 165 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 139 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 of this rigid body, which enables transformation between the local rigid body coordinates global coordinates

Definition at line 215 of file rigid_bodies.h.

Here is the call graph for this function:

IMP::algebra::Rotation3D IMP::core::RigidBody::get_rotation ( ) const

returns the rotation of the particle (= rotation from local to global rigid body orientation)

Definition at line 208 of file rigid_bodies.h.

static FloatKeys IMP::core::RigidBody::get_rotation_keys ( )

static

Get keys for rotation quaternion.

Definition at line 133 of file rigid_bodies.h.

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 478 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::pull_back_body_member_adjoints	(	ParticleIndex	pi,
		DerivativeAccumulator &	da
	)

Pull back global adjoints from member that is also a rigid body.

Parameters

pi	index of member particle
da	accumulator for the adjoints

void IMP::core::RigidBody::pull_back_body_member_adjoints	(	ParticleIndex	pi,
		const algebra::Transformation3D &	TA,
		algebra::Transformation3D &	TB,
		algebra::Transformation3DAdjoint &	DTC,
		algebra::Transformation3DAdjoint &	DTA,
		algebra::Transformation3DAdjoint &	DTB,
		algebra::Vector3D &	betatorque,
		DerivativeAccumulator &	da
	)

Same as above, but uses fewer allocations.

Parameters

pi	index of member particle
TA	transformation from this body's local coordinates to global
TB	transformation from member's local coordinates to this body's local coordinates
DTC	adjoint on composition of TA and TB, which is the transformation from the member's local coordinates to global
DTA	adjoint on TA
DTB	adjoint on TB
betatorque	torque contribution from DTC in local coordinates at beta, the position of the member in local coordinates.
da	accumulator for the adjoints

void IMP::core::RigidBody::pull_back_member_adjoints	(	ParticleIndex	pi,
		DerivativeAccumulator &	da
	)

Pull back global adjoints from member that is a point.

Parameters

pi	index of member particle
da	accumulator for the adjoints

void IMP::core::RigidBody::pull_back_member_adjoints	(	ParticleIndex	pi,
		const algebra::Transformation3D &	T,
		algebra::Vector3D &	x,
		algebra::Vector3D &	Dy,
		algebra::Vector3D &	Dx,
		algebra::Transformation3DAdjoint &	DT,
		algebra::Vector3D &	xtorque,
		DerivativeAccumulator &	da
	)

Same as above, but uses fewer allocations.

Parameters

pi	index of member particle
T	transformation from this body's local coordinates to global
x	local coordinates of the member
Dy	adjoint on the member's global coordinates
Dx	adjoint on the member's local coordinates
DT	adjoint on the transformation
xtorque	torque contribution from Dy in local coordinates
da	accumulator for the adjoints

void IMP::core::RigidBody::pull_back_members_adjoints ( DerivativeAccumulator & da )

Pull back global adjoints from members.

Adjoints (reverse-mode sensitivities) are partial derivatives of the score with respect to intermediate values in the scoring function computation, such as the global coordinates of a bead within a rigid body or the global reference frame of a nested rigid body.

This function pulls back (back-propagates) global adjoints and local torque on all members to the global rotation, global coordinates, and local torque on this rigid body and the internal coordinates and rotation of any non-rigid members.

This is called by an internal score state after scoring function evaluation and is not meant to be called by the user.

void IMP::core::RigidBody::remove_member ( ParticleIndexAdaptor p )

Remove the member from this rigid body.

The member can be either a rigid body member or a point member, either rigid or non-rigid.

The radius of the rigid body is updated to reflect the removed member.

Exceptions

UsageException if the given particle is not a member of this body.

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.

The radius of the rigid body is updated to reflect this change.

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

Definition at line 250 of file rigid_bodies.h.

Here is the call graph for this function:

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.

Returns: a RigidBody object that decorates particle pi

Definition at line 180 of file rigid_bodies.h.

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

static

Returns: a RigidBody object that decorates the particle specified by pa

See Also: setup_particle(m, pi, ps )

Definition at line 180 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.

Returns: a RigidBody object that decorates particle pi

Definition at line 186 of file rigid_bodies.h.

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

static

Returns: a RigidBody object that decorates the particle specified by pa

See Also: setup_particle(m, pi, rf )

Definition at line 186 of file rigid_bodies.h.

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

static

Make the rigid body no longer rigid.

If this rigid body has been added as a member of another rigid body, it must be removed first.

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