DistanceRestraintForce< AT, CT > Class Template Reference

Computes one or more flattened distance-restraint terms. More...

#include <DistanceRestraintForce.h>

Public Member Functions
	DistanceRestraintForce (void)=delete
	Prevents construction without an explicit atom count.
	DistanceRestraintForce (const int numAtoms)
	Constructs a distance-restraint force for a fixed atom count.
	DistanceRestraintForce (const DistanceRestraintForce &other)=delete
	Prevents copying CUDA stream and output ownership state.
	DistanceRestraintForce (DistanceRestraintForce &&other)=delete
	Prevents moving a force whose object identity and CUDA resources may be retained by a force manager.
DistanceRestraintForce &	operator= (const DistanceRestraintForce &other)=delete
	Prevents copy assignment of CUDA stream and output ownership state.
DistanceRestraintForce &	operator= (DistanceRestraintForce &&other)=delete
	Prevents move assignment of CUDA stream and output ownership state.
	~DistanceRestraintForce (void) noexcept
	Releases owned CUDA and output resources.
void	setScale (const double scale)
	Sets the global scale applied to every active restraint term.
void	addRestraint (const std::vector< std::array< AtomReference, 2 > > &atomReferencePairs, const std::vector< double > &coefficients, const double forceConstant, const double referenceValue, const int distanceExponent, const int energyExponent, const DistanceRestraintCondition condition=DistanceRestraintCondition::NONE)
	Appends one restraint term from topology-aware atom references.
void	reset (void)
	Removes every restraint term and restores the global scale to one.
void	setBoxDimensions (const std::vector< double > &boxDimensions)
	Stores the current three box dimensions.
void	initialize (const int numAtoms, const std::vector< double > &boxDimensions)
	Initializes the restraint through the ForceManager interface.
void	clear (void)
	Enqueues clearing of accumulated force, energy, and virial output.
void	calcForce (const float4 *xyzq, const bool calcEnergy, const bool calcVirial)
	Enqueues distance-restraint force and optional energy and virial accumulation.
std::shared_ptr< cudaStream_t >	getStream (void)
	Returns shared access to the privately owned CUDA stream holder.
std::shared_ptr< Force< AT > >	getForce (void)
	Returns shared ownership of the atom-sized device force storage.
std::shared_ptr< CudaEnergyVirial >	getEnergyVirial (void)
	Returns shared ownership of the energy and virial storage.

Static Public Attributes
static constexpr bool	contributesVirial = true
	Reports that this restraint contributes virial state.

Detailed Description

template<typename AT, typename CT>
class DistanceRestraintForce< AT, CT >

Computes one or more flattened distance-restraint terms.

For term t, the associated pairs occupy the half-open flattened range [m_TermPairOffsets[t], m_TermPairOffsets[t + 1]). For pair coefficient c_tj, raw primary-coordinate distance r_tj, distance exponent IVAL_t, reference value RVAL_t, force constant KVAL_t, energy exponent EVAL_t, and global scale SCALE, an active term uses:

D_t = sum_j(c_tj * r_tj^IVAL_t) - RVAL_t
U_t = SCALE * (KVAL_t / EVAL_t) * D_t^EVAL_t

One object may own multiple terms. addRestraint() accepts topology-aware endpoint pairs, extracts each endpoint's zero-based atom index, and appends one term and its pair data to flattened host mirrors. The corresponding device mirrors are synchronized lazily before calculation.

The force remains atom-count based and topology-agnostic. It does not retain AtomReference objects, retain a CharmmPSF, compare source topologies, or require the two endpoints of a pair to originate from the same topology. Only the extracted integer indices are stored.

The controlling characterization requires raw primary-coordinate pair distances for the characterized nonperiodic and orthorhombic P1 cases. Stored box dimensions satisfy the ForceManager lifecycle and do not imply minimum-image replacement of those pair distances.

Template Parameters

AT	Device force-accumulator representation. The supported public specializations use apoCHARMM's fixed-point force representation.
CT	Arithmetic representation used for pair-gradient conversion to the device force accumulator.

Warning

The complete accepted ranges of the distance and energy exponents remain unresolved outside the characterized values.

Nonorthorhombic, non-P1, and other uncharacterized periodic or image configurations remain unsupported and must not be inferred.

Every evaluated exact zero-distance pair is rejected before exponentiation or gradient formation.

The class provides no internal host-thread synchronization. Callers must serialize configuration, clearing, calculation, and destruction.

See also

ForceManager

Constructor & Destructor Documentation

DistanceRestraintForce()

template<typename AT , typename CT >

DistanceRestraintForce< AT, CT >::DistanceRestraintForce

(

const int

numAtoms

)

Constructs a distance-restraint force for a fixed atom count.

The object initially owns no restraint terms. The confirmed initial global scale is one. The atom count remains fixed for the lifetime of the object.

Parameters

[in]

numAtoms

Dimensionless number of atoms represented by coordinate and force arrays.

Member Function Documentation

addRestraint()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::addRestraint	(	const std::vector< std::array< AtomReference, 2 > > &	atomReferencePairs,
		const std::vector< double > &	coefficients,
		const double	forceConstant,
		const double	referenceValue,
		const int	distanceExponent,
		const int	energyExponent,
		const DistanceRestraintCondition	condition = DistanceRestraintCondition::NONE
	)

Appends one restraint term from topology-aware atom references.

atomReferencePairs and coefficients are parallel vectors and must have matching lengths. Both vectors are borrowed only for this call. The coefficient values and each endpoint's zero-based atom index are copied into force-owned host storage.

Topology provenance is deliberately ignored. This method does not call AtomReference::hasSameTopology(), does not require pair endpoints to originate from the same topology, and retains neither the references nor their source CharmmPSF objects after returning. The force stores only the values returned by AtomReference::getAtomIndex().

Each extracted index must be in the force-local range [0, numAtoms), even when the reference is valid for a larger source topology. The two extracted indices in one pair must be distinct. References from different topologies with distinct valid extracted indices are accepted; references from different topologies with the same extracted index are rejected.

Pair order and coefficient correspondence are preserved exactly. Repeated pairs remain accepted.

The distance exponent remains a required argument because the following energy exponent has no confirmed default. The activation condition defaults to NONE, corresponding to the confirmed absence of a one-sided selector.

Parameters

[in]	atomReferencePairs	Atom-reference endpoint pairs belonging to this term.
[in]	coefficients	Algebraic coefficient corresponding to each pair.
[in]	forceConstant	Nonzero term force constant.
[in]	referenceValue	Term reference value.
[in]	distanceExponent	Integer exponent applied to each pair distance.
[in]	energyExponent	Integer exponent applied to the term deviation.
[in]	condition	One-sided activation mode.

calcForce()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::calcForce	(	const float4 *	xyzq,
		const bool	calcEnergy,
		const bool	calcVirial
	)

Enqueues distance-restraint force and optional energy and virial accumulation.

Dirty flattened parameter mirrors are synchronized before their device data are consumed. Exact zero-distance pairs terminate device evaluation before exponentiation or gradient formation. A zero global scale returns before geometry is read.

Parameters

[in]	xyzq	Borrowed CUDA-device coordinate-charge array.
[in]	calcEnergy	Whether to accumulate the restraint energy.
[in]	calcVirial	Whether to accumulate the restraint virial.

clear()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::clear

(

void

)

Enqueues clearing of accumulated force, energy, and virial output.

This operation does not remove stored restraint terms and does not restore the global scale.

initialize()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::initialize	(	const int	numAtoms,
		const std::vector< double > &	boxDimensions
	)

Initializes the restraint through the ForceManager interface.

Parameters

[in]	numAtoms	Atom count supplied by the manager.
[in]	boxDimensions	Three box lengths in [x, y, z] order.

reset()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::reset

(

void

)

Removes every restraint term and restores the global scale to one.

Output force, energy, and virial storage are not substituted for the term reset operation; use clear() to clear accumulated output.

setBoxDimensions()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::setBoxDimensions

(

const std::vector< double > &

boxDimensions

)

Stores the current three box dimensions.

The dimensions are retained for ForceManager compatibility. They must not cause the characterized raw primary-coordinate pair distances to be replaced by minimum-image distances.

Parameters

[in]

boxDimensions

Three box lengths in [x, y, z] order.

setScale()

template<typename AT , typename CT >

void DistanceRestraintForce< AT, CT >::setScale

(

const double

scale

)

Sets the global scale applied to every active restraint term.

The characterized behavior accepts positive, zero, and negative finite scale values. The scale is host scalar state and does not alter stored term definitions.

Parameters

[in]

scale

Global multiplicative scale.