IMP Reference Guide
2.12.0
The Integrative Modeling Platform
|
A decorator for a rigid body. More...
#include <IMP/core/rigid_bodies.h>
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:
Definition at line 82 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) |
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... | |
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 | 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 decorator, ParticleIndexesAdaptor ps) |
static RigidBody | setup_particle (Model *m, ParticleIndex pi, ParticleIndexesAdaptor ps) |
static RigidBody | setup_particle (IMP::ParticleAdaptor decorator, 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 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) | |
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.
void IMP::core::RigidBody::add_non_rigid_member | ( | ParticleIndexAdaptor | p | ) |
Add a non-rigid member, for which internal coordinates may change independently.
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 speicified location (the point where the force is being applied).
Updates both the quaternion derivatives and the torque.
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.
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.
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.
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)
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 146 of file rigid_bodies.h.
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 196 of file rigid_bodies.h.
bool IMP::core::RigidBody::get_coordinates_are_optimized | ( | ) | const |
Returns true if the rigid body coordinates are flagged as optimized for Optimizer objects
|
static |
Return true if the particle is a rigid body.
Definition at line 189 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 159 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 133 of file rigid_bodies.h.
IMP::algebra::ReferenceFrame3D IMP::core::RigidBody::get_reference_frame | ( | ) | const |
Get the reference frame of this rigid body, which enables trnasformation between the local rigid body coordinates global coordinates
Definition at line 207 of file rigid_bodies.h.
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 200 of file rigid_bodies.h.
|
static |
Get keys for rotation quaternion.
Definition at line 127 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 470 of file rigid_bodies.h.
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.
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.
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.
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.
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::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.
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.
void IMP::core::RigidBody::set_reference_frame_lazy | ( | const IMP::algebra::ReferenceFrame3D & | tr | ) |
Change the reference, delay updating the members until evaluate.
Definition at line 242 of file rigid_bodies.h.
|
static |
Definition at line 174 of file rigid_bodies.h.
|
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.
Definition at line 174 of file rigid_bodies.h.
|
static |
Definition at line 180 of file rigid_bodies.h.
|
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 180 of file rigid_bodies.h.
|
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