MassCenterMotionRemover Class Reference

This is an event handler that can remove from a molecular system any unwanted "rigid body" motion of the sytem as a whole. More...

#include <MassCenterMotionRemover.h>

Inheritance diagram for MassCenterMotionRemover:

List of all members.

Public Member Functions
	MassCenterMotionRemover (const MolecularMechanicsSystem &system, Real adjustmentInterval=1)
	Create a MassCenterMotionRemover implemented as a periodic event handler; the default behavior is that system linear and angular momentum will be removed but the mass center will not be relocated.
MassCenterMotionRemover &	disableAngularMomentumRemoval (bool disable)
	Enable or disable removal of system angular momentum (enabled by default).
bool	isAngularMomentumRemovalDisabled () const
	Find out whether this handler is currently set to remove system angular momentum; if this returns true then only linear momentum is being removed.
MassCenterMotionRemover &	enableMassCenterCorrection (bool enabled)
	Enable or disable adjustment of the system mass center location (disabled by default).
bool	isMassCenterCorrectionEnabled () const
	Find out whether this handler is currently set to reposition the system mass center if it drifts; if this returns false then the system mass center will not be monitored or controlled.
MassCenterMotionRemover &	setDesiredMassCenterLocation (const Vec3 &groundLocationInNm)
	Set the desired location (as a Ground frame Vec3 in nm) to which the system mass center is to be repositioned if it moves away by more than the currently set tolerance (no effect unless mass center correction has been enabled).
const Vec3 &	getDesiredMassCenterLocation () const
	Obtain the current value of the desired mass center location.
MassCenterMotionRemover &	setMassCenterLocationTolerance (Real toleranceInNm)
	Set the tolerance (in nm) for the allowable system mass center drift before the handler will reposition it (no effect unless mass center correction has been enabled).
Real	getMassCenterLocationTolerance () const
	Obtain the current value of the mass center location tolerance in nm.
void	removeSystemMomentum (State &state) const
	Attempt to remove the system's central linear momentum and angular momentum unless that has been disabled.
void	correctMassCenterLocation (State &state) const
	Attempt to move the system mass center in the given State to this handler's currently set desired mass center location.
Real	calcMassCenterError (const State &state) const
	Determine the current distance of the system mass center from the currently set desired mass center location.

---

Detailed Description

This is an event handler that can remove from a molecular system any unwanted "rigid body" motion of the sytem as a whole.

This is useful systems for which you expect conservation of momentum to prevent overall motion, but where numerical error or non-conservative disturbances (like the VelocityRescalingThermostat) may lead to unwanted motion. The handler will remove overall linear and (optionally) angular momentum, and can also reposition the center of mass if it has drifted from a desired location.

---

Constructor & Destructor Documentation

MassCenterMotionRemover	(	const MolecularMechanicsSystem &	system,
		Real	adjustmentInterval = 1
	)			[inline, explicit]

Create a MassCenterMotionRemover implemented as a periodic event handler; the default behavior is that system linear and angular momentum will be removed but the mass center will not be relocated.

You can change the default behavior with the methods mentioned below.

Parameters:

[in]	system	The MolecularMechanicsSystem containing the bodies to be affected. Typically this will be a Molmodel CompoundSystem (which is a kind of MolecularMechanicsSystem).
[in]	adjustmentInterval	The time interval (in ps) at which to adjust the momentum and possibly relocate the mass center. The default value is 1ps.

See also:

disableAngularMomentumRemoval(), enableMassCenterCorrection()

---

Member Function Documentation

Real calcMassCenterError

(

const State &

state

)

const [inline]

Determine the current distance of the system mass center from the currently set desired mass center location.

The error is calculated regardless of whether mass center correction is currently enabled.

Parameters:

[in]

state

The State from which the current system mass center location is determined.

Returns:

The distance of the current system mass center location from the desired location, measured in nm.

References MolecularMechanicsSystem::calcSystemMassCenterLocation(), and SimTK::norm().

void correctMassCenterLocation

(

State &

state

)

const [inline]

Attempt to move the system mass center in the given State to this handler's currently set desired mass center location.

Tolerance is not checked.

Parameters:

[in,out]

state

The State from which the current system mass center location is determined and to which the correction is applied.

References MolecularMechanicsSystem::moveSystemMassCenter().

MassCenterMotionRemover& disableAngularMomentumRemoval

(

bool

disable

)

[inline]

Enable or disable removal of system angular momentum (enabled by default).

If you set this flag to false then only linear momentum will be removed. There is no way to disable linear momentum removal.

Parameters:

[in]

disable

Set to true if you want the handler only to remove linear momentum. Otherwise both linear and angular momentum are removed, which is the default behavior.

Returns:

A reference to this object (that was just modified).

MassCenterMotionRemover& enableMassCenterCorrection

(

bool

enabled

)

[inline]

Enable or disable adjustment of the system mass center location (disabled by default).

If you set this flag to true then the handler will check if the system mass center has drifted by more than the specified tolerance, and if so will attempt to move the system mass center back to the specified desired location. Note that there are default values of the tolerance (1 nm) and the desired location (0,0,0) if you haven't set them explicitly.

Parameters:

[in]

enabled

Set to true if you want the handler to attempt to keep the system mass center fixed; false if you want to leave it alone. Mass center location correction is disabled by default.

Returns:

A reference to this object (that was just modified).

const Vec3& getDesiredMassCenterLocation

(

)

const [inline]

Obtain the current value of the desired mass center location.

This is where the mass center will be relocated to if mass center relocation is enabled.

Real getMassCenterLocationTolerance

(

)

const [inline]

Obtain the current value of the mass center location tolerance in nm.

If mass center correction is enabled, this is how far the mass center can drift before it gets corrected.

bool isAngularMomentumRemovalDisabled

(

)

const [inline]

Find out whether this handler is currently set to remove system angular momentum; if this returns true then only linear momentum is being removed.

bool isMassCenterCorrectionEnabled

(

)

const [inline]

Find out whether this handler is currently set to reposition the system mass center if it drifts; if this returns false then the system mass center will not be monitored or controlled.

void removeSystemMomentum

(

State &

state

)

const [inline]

Attempt to remove the system's central linear momentum and angular momentum unless that has been disabled.

Parameters:

[in,out]

state

The State from which the current system momentum is determined and to which the correction is applied.

References MolecularMechanicsSystem::removeSystemRigidBodyMomentum().

MassCenterMotionRemover& setDesiredMassCenterLocation

(

const Vec3 &

groundLocationInNm

)

[inline]

Set the desired location (as a Ground frame Vec3 in nm) to which the system mass center is to be repositioned if it moves away by more than the currently set tolerance (no effect unless mass center correction has been enabled).

Parameters:

[in]

groundLocationInNm

When the adjustmentInterval has elapsed, the handler will compare the current system mass center location with this location and move it if it has drifted beyone the specified tolerance.

Returns:

A reference to this object (that was just modified).

See also:

setMassCenterLocationTolerance()

MassCenterMotionRemover& setMassCenterLocationTolerance

(

Real

toleranceInNm

)

[inline]

Set the tolerance (in nm) for the allowable system mass center drift before the handler will reposition it (no effect unless mass center correction has been enabled).

If you want to disable mass center correction it is more efficent to call enableMassCenterCorrection(false) than to set this to a large value.

Parameters:

[in]

toleranceInNm

When the adjustmentInterval has elapsed, the handler will compare the current system mass center with the desired location and move it if it has drifted beyone the specified tolerance which is given in nm. The default is 1 nm (10 Angstroms). The default for the desired mass center location is (0,0,0) but you can change that using setDesiredMassCenterLocation().

Returns:

A reference to this object (that was just modified).

See also:

setDesiredMassCenterLocation(), enableMassCenterCorrection()

References SimTK_APIARGCHECK1_ALWAYS.

---

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

• MassCenterMotionRemover.h