Owns and coordinates native GPU force-evaluation backends. More...

#include <ForceManager.h>

Inherits std::enable_shared_from_this< ForceManager >.

Public Member Functions
	ForceManager (void)
	Constructs an uninitialized manager with default configuration.

	ForceManager (std::shared_ptr< CharmmPSF > psf, std::shared_ptr< CharmmParameters > prm)
	Constructs an uninitialized manager from a PSF and parameter set.

	ForceManager (const ForceManager &other)
	Constructs a configuration-only deep copy of another manager.

virtual	~ForceManager (void) noexcept
	Destroys the manager and releases its owned native resources.

void	setContext (std::shared_ptr< CharmmContext > ctx)
	Stores a non-owning association with a `CharmmContext`.

void	setPsf (std::shared_ptr< CharmmPSF > psf)
	Sets the PSF retained by the manager.

void	setPrm (std::shared_ptr< CharmmParameters > prm)
	Sets the parameter set retained by the manager.

void	addPsf (const std::filesystem::path &psfPath)
	Loads and installs a PSF from a file.

void	addPrm (const std::filesystem::path &prmPath)
	Loads and installs parameters from one file.

void	addPrm (const std::vector< std::filesystem::path > &prmList)
	Loads and installs parameters from an ordered list of files.

virtual void	setBoxDimensions (const std::vector< double > &size)
	Sets the orthorhombic box dimensions.

virtual void	setKappa (const float kappa)
	Sets the Ewald splitting parameter.

virtual void	setCutoff (const float cutoff)
	Sets the direct-space pair-list cutoff.

virtual void	setCtonnb (const float ctonnb)
	Sets the outer nonbonded switching distance exposed as `ctonnb`.

virtual void	setCtofnb (const float ctofnb)
	Sets the inner nonbonded switching distance exposed as `ctofnb`.

virtual void	setFFTGrid (const int nfftx, const int nffty, const int nfftz)
	Sets the three PME FFT grid dimensions.

virtual void	setPmeSplineOrder (const int pmeSplineOrder)
	Sets the PME interpolation spline order.

virtual void	setPeriodicBoundaryCondition (const PBC pbc)
	Sets the periodic boundary condition.

virtual void	setVdwType (const int vdwType)
	Sets the native van der Waals model code.

void	setPrintEnergyDecomposition (const bool printEnergyDecomposition=true)
	Enables or disables energy-decomposition printing.

virtual void	addForceManager (std::shared_ptr< ForceManager > fm)
	Rejects child managers in the non-composite base implementation.

std::shared_ptr< CharmmContext >	getContext (void)
	Returns the associated `CharmmContext` when it is still alive.

bool	hasCharmmContext (void) const
	Reports whether the associated `CharmmContext` is still alive.

virtual std::shared_ptr< CharmmPSF >	getPsf (void)
	Returns the retained PSF.

std::shared_ptr< CharmmParameters >	getPrm (void)
	Returns the retained parameter set.

virtual bool	isInitialized (void) const
	Reports whether native force initialization completed.

const CudaContainer< int4 > &	getShakeAtoms (void) const
	Returns read-only SHAKE atom-index records.

CudaContainer< int4 > &	getShakeAtoms (void)
	Returns mutable SHAKE atom-index records.

const CudaContainer< float4 > &	getShakeParams (void) const
	Returns read-only SHAKE parameter records.

CudaContainer< float4 > &	getShakeParams (void)
	Returns mutable SHAKE parameter records.

const CudaEnergyVirial &	getBondedEnergyVirial (void) const
	Returns read-only bonded energy and virial state.

CudaEnergyVirial &	getBondedEnergyVirial (void)
	Returns mutable bonded energy and virial state.

const CudaEnergyVirial &	getReciprocalEnergyVirial (void) const
	Returns read-only reciprocal energy and virial state.

CudaEnergyVirial &	getReciprocalEnergyVirial (void)
	Returns mutable reciprocal energy and virial state.

const CudaEnergyVirial &	getDirectEnergyVirial (void) const
	Returns read-only direct-space energy and virial state.

CudaEnergyVirial &	getDirectEnergyVirial (void)
	Returns mutable direct-space energy and virial state.

std::map< std::string, double >	getEnergyComponents (void)
	Returns the current host-side energy decomposition.

std::shared_ptr< cudaStream_t >	getBondedStream (void)
	Returns the bonded-force CUDA stream holder.

std::shared_ptr< cudaStream_t >	getReciprocalStream (void)
	Returns the reciprocal-force CUDA stream holder.

std::shared_ptr< cudaStream_t >	getDirectStream (void)
	Returns the direct-force CUDA stream holder.

std::shared_ptr< cudaStream_t >	getForceManagerStream (void)
	Returns the aggregate-force CUDA stream holder.

std::shared_ptr< Force< long long int > >	getBondedForcevalues (void)
	Returns synchronized bonded fixed-point force storage.

std::shared_ptr< Force< long long int > >	getReciprocalForcevalues (void)
	Returns synchronized reciprocal fixed-point force storage.

std::shared_ptr< Force< long long int > >	getDirectForcevalues (void)
	Returns synchronized direct-space fixed-point force storage.

std::shared_ptr< Force< double > >	getTotalForcevalues (void)
	Returns synchronized aggregate double-precision force storage.

virtual std::shared_ptr< Force< double > >	getForces (void)
	Returns the aggregate double-precision force storage.

int	getForceStride (void) const
	Returns the component stride of aggregate force storage.

virtual const std::vector< double > &	getBoxDimensions (void) const
	Returns read-only stored box dimensions.

virtual std::vector< double > &	getBoxDimensions (void)
	Returns mutable stored box dimensions.

float	getKappa (void) const
	Returns the stored Ewald splitting parameter.

float	getCutoff (void) const
	Returns the stored pair-list cutoff.

float	getCtonnb (void) const
	Returns the stored outer switching distance exposed as `ctonnb`.

float	getCtofnb (void) const
	Returns the stored inner switching distance exposed as `ctofnb`.

std::vector< int >	getFFTGrid (void) const
	Returns the three stored PME FFT grid dimensions.

int	getPmeSplineOrder (void) const
	Returns the PME interpolation spline order.

PBC	getPeriodicBoundaryCondition (void) const
	Returns the stored periodic boundary condition.

virtual CudaContainer< double > &	getPotentialEnergy (void)
	Returns aggregate potential-energy storage.

virtual float	getPotentialEnergies (void)
	Returns the current standard potential-energy sum on the host.

virtual CudaContainer< double > &	getVirial (void)
	Sums standard and eligible subscribed virial contributions.

int	getVdwType (void) const
	Returns the native van der Waals model code.

virtual bool	isComposite (void) const
	Reports whether this manager is composite.

virtual const std::vector< std::shared_ptr< ForceManager > > &	getChildren (void) const
	Returns read-only child-manager storage.

virtual std::vector< std::shared_ptr< ForceManager > > &	getChildren (void)
	Returns mutable child-manager storage.

virtual void	initialize (void)
	Initializes all native force-evaluation state.

virtual void	resetNeighborList (const float4 *xyzq)
	Rebuilds the direct-space neighbor list for current coordinates.

void	calcForcePart1 (const bool reset, const bool calcEnergy, const bool calcVirial)
	Clears force and requested energy-virial state.

void	calcForcePart2 (const float4 *xyzq, const bool calcEnergy, const bool calcVirial)
	Enqueues all built-in and subscribed force calculations.

void	calcForcePart3 (const float4 *xyzq, const bool calcEnergy, const bool calcVirial)
	Synchronizes component work and assembles aggregate outputs.

virtual void	calcForce (const float4 *xyzq, const bool reset=false, const bool calcEnergy=false, const bool calcVirial=false)
	Computes aggregate forces and optional energy and virial outputs.

template<typename ForceType >
void	subscribe (std::shared_ptr< ForceType > force, const std::string &forceTag, std::shared_ptr< cudaStream_t > forceStream, std::shared_ptr< Force< long long int > > forceValues, std::shared_ptr< CudaEnergyVirial > energyVirial)
	Subscribes an additional force and its CUDA resources.

template<typename ForceType >
void	unsubscribe (std::shared_ptr< ForceType > force)
	Unsubscribes a force by object identity.

void	unsubscribe (const std::string &forceTag)
	Unsubscribes the first force with a matching tag.

virtual CudaContainer< double >	computeAllChildrenPotentialEnergy (const float4 *xyzq)
	Rejects child-energy evaluation in the base manager.

Protected Member Functions
void	initializeHolonomicConstraintsVariables (void)
	Builds GPU SHAKE records from PSF bonds and parameter data.

std::vector< int >	computeFFTGridSize (void)
	Computes automatic even PME FFT grid dimensions.

void	checkBoxDimensions (const std::vector< double > &boxDimensions)
	Validates an orthorhombic box-dimension vector.

Protected Attributes
std::weak_ptr< CharmmContext >	m_Context

std::shared_ptr< CharmmPSF >	m_Psf

std::shared_ptr< CharmmParameters >	m_Prm

bool	m_IsInitialized

bool	m_BondedForceDirty

bool	m_ReciprocalForceDirty

bool	m_DirectForceDirty

CudaContainer< int4 >	m_ShakeAtoms

CudaContainer< float4 >	m_ShakeParams

CudaEnergyVirial	m_BondedEnergyVirial

std::shared_ptr< cudaStream_t >	m_BondedStream

std::shared_ptr< cudaStream_t >	m_ForceManagerStream

std::shared_ptr< Force< long long int > >	m_BondedForceValues

std::shared_ptr< Force< double > >	m_TotalForceValues

float	m_BoxX

std::vector< double >	m_BoxDimensions

float	m_Kappa

float	m_Cutoff

float	m_Ctonnb

float	m_Ctofnb

int	m_NfftX

int	m_PmeSplineOrder

PBC	m_Pbc

std::unique_ptr< CudaBondedForce< long long int, float > >	m_BondedForcePtr

CudaContainer< double >	m_TotalPotentialEnergy

CudaContainer< double >	m_BondedVirial

bool	m_ClearGraphCreated

std::vector< std::shared_ptr< void > >	m_ForcePtrs

bool	m_ComputeDirectSpaceForces

int	m_VdwType

std::vector< std::shared_ptr< ForceManager > >	m_Children

bool	m_PrintEnergyDecomposition

Detailed Description

Owns and coordinates native GPU force-evaluation backends.

A ForceManager combines a CharmmPSF and CharmmParameters with box, Ewald, cutoff, FFT-grid, spline, periodic-boundary, and van der Waals configuration. Initialization constructs the bonded, direct-space, and reciprocal-space CUDA backends, creates their streams and force storage, initializes already subscribed forces, and allocates aggregate force, energy, virial, and holonomic-constraint state.

The manager retains shared ownership of its PSF and parameter set. Its association with a CharmmContext is weak and does not extend the context's lifetime. Subscribed force objects and their associated streams, force arrays, and energy-virial objects are retained through shared ownership until they are unsubscribed or the manager is destroyed.

Before initialization, callers must supply a PSF, a parameter set, and three positive box lengths. Configuration setters should normally be called before the first initialization. Several setters update stored configuration without rebuilding an already active backend.

Force calculations consume a device-resident float4 coordinate-charge array and produce device-resident structure-of-arrays force storage. Component calculations use separate CUDA streams and are synchronized before the aggregate force is returned as complete.

The base class is non-composite. Derived managers may override the child, initialization, force, and potential-energy extension points.

Warning: ForceManager provides no internal synchronization for concurrent host access. Configuration, subscription, initialization, force evaluation, and mutable accessor use must be externally serialized.; Initialization is not transactional. A failure can leave partially allocated native or CUDA state while isInitialized() remains false.

See also: force_manager

Constructor & Destructor Documentation

◆ ForceManager() [1/3]

ForceManager::ForceManager ( void )

Constructs an uninitialized manager with default configuration.

The manager initially has no PSF, no parameter set, no context, no CUDA force backends, and sentinel box dimensions. Its defaults are:

Ewald splitting parameter 0.34 inverse angstroms;
pair-list cutoff 14.0 angstroms;
outer switching distance exposed as ctonnb, 12.0 angstroms;
inner switching distance exposed as ctofnb, 10.0 angstroms;
automatic FFT dimensions, represented by -1 on each axis;
PME spline order 4;
periodic boundary condition PBC::P1;
van der Waals model VDW_VFSW; and
disabled energy-decomposition printing.

Five nine-element virial work containers are allocated and initialized to zero during construction.

Postcondition: isInitialized() returns false.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::Cuda if virial storage allocation or initialization fails in CUDA.
std::bad_alloc	If host-side object or container allocation fails.

◆ ForceManager() [2/3]

ForceManager::ForceManager	(	std::shared_ptr< CharmmPSF >	psf,
		std::shared_ptr< CharmmParameters >	prm
	)

Constructs an uninitialized manager from a PSF and parameter set.

The manager retains shared ownership of both collaborators; it does not copy either object. CUDA force backends are not created until initialize() is called directly or through a CharmmContext.

Parameters

[in]	psf	Shared owner of a non-null PSF. The manager retains a copy of the shared pointer.
[in]	prm	Shared owner of a non-null parameter set. The manager retains a copy of the shared pointer.

Postcondition: getPsf() and getPrm() share ownership with the supplied objects.; isInitialized() returns false.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if `psf` or `prm` is null.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if default virial storage construction fails.
std::bad_alloc	If host-side allocation fails.

◆ ForceManager() [3/3]

ForceManager::ForceManager ( const ForceManager & other )

Constructs a configuration-only deep copy of another manager.

A non-null PSF and parameter set are copied into independent CharmmPSF and CharmmParameters objects. Box dimensions, Ewald and cutoff values, FFT dimensions, spline order, periodic-boundary condition, and van der Waals model are copied.

The context association, initialized state, CUDA streams, CUDA backends, force arrays, energy and virial values, subscribed forces, children, CUDA clear graph, and print-energy flag are not copied. They retain the default constructor state in the new manager.

Parameters

[in] other Manager whose configuration is copied. The source remains unchanged.

Postcondition: The new manager is uninitialized and has no associated context.; Any copied PSF and parameter set are independent of other.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::Cuda if default virial storage construction or a copied CUDA-backed collaborator fails.
std::bad_alloc	If collaborator or container allocation fails.

◆ ~ForceManager()

virtual ForceManager::~ForceManager ( void )

virtualnoexcept

Destroys the manager and releases its owned native resources.

CUDA streams and cached graph objects are destroyed through non-throwing cleanup paths. Cleanup failures are discarded. Shared ownership of the PSF, parameter set, subscribed-force resources, and force arrays is released.

A separately retained PSF, parameter set, subscribed force, or force-array shared pointer may outlive the manager. A shared pointer returned by a stream getter may keep the host cudaStream_t value allocated, but the manager still destroys the underlying CUDA stream, so that handle must not be used after manager destruction.

Postcondition: Borrowed references returned by this manager are invalid.

Member Function Documentation

◆ addForceManager()

virtual void ForceManager::addForceManager ( std::shared_ptr< ForceManager > fm )

virtual

Rejects child managers in the non-composite base implementation.

Derived composite managers override this extension point.

Parameters

[in] fm Proposed child manager.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if `fm` is null.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime for every non-null `fm`, because the base manager does not support children.

◆ addPrm() [1/2]

void ForceManager::addPrm ( const std::filesystem::path & prmPath )

Loads and installs parameters from one file.

A new CharmmParameters is constructed from prmFile. The existing parameter set is replaced only after construction succeeds, then the initialized flag is cleared.

Parameters

[in] prmPath Non-empty file-system path to a CHARMM parameter or stream file.

Postcondition: On success, getPrm() owns the newly parsed parameter set and isInitialized() returns false.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the file cannot be read or a parameter record is invalid.
std::bad_alloc	If parsing or collaborator allocation fails.

Warning: Existing initialized CUDA force state is not deallocated by this call.

◆ addPrm() [2/2]

void ForceManager::addPrm ( const std::vector< std::filesystem::path > & prmList )

Loads and installs parameters from an ordered list of files.

Files are parsed in prmList order into one new CharmmParameters object. The existing parameter set is replaced only after all files are parsed successfully, then the initialized flag is cleared.

Parameters

[in] prmList Non-empty ordered list of file-system paths to CHARMM parameter or stream files.

Postcondition: On success, getPrm() owns the newly parsed parameter set and isInitialized() returns false.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if `prmList` is empty.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if a file cannot be read or a parameter record is invalid.
std::bad_alloc	If parsing or collaborator allocation fails.

Warning: Existing initialized CUDA force state is not deallocated by this call.

◆ addPsf()

void ForceManager::addPsf ( const std::filesystem::path & psfPath )

Loads and installs a PSF from a file.

A new CharmmPSF is constructed from psfFile. The existing PSF is replaced only after construction succeeds, then the initialized flag is cleared.

Parameters

[in] psfPath Non-empty file-system path to the CHARMM PSF file.

Postcondition: On success, getPsf() owns the newly parsed PSF and isInitialized() returns false.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the file cannot be read or its PSF records are invalid.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if construction of CUDA-backed PSF data fails.
std::bad_alloc	If parsing or collaborator allocation fails.

Warning: Existing initialized CUDA force state is not deallocated by this call.

◆ calcForce()

virtual void ForceManager::calcForce	(	const float4 *	xyzq,
		const bool	reset = `false`,
		const bool	calcEnergy = `false`,
		const bool	calcVirial = `false`
	)

virtual

Computes aggregate forces and optional energy and virial outputs.

This convenience method calls calcForcePart1(), calcForcePart2(), and calcForcePart3() in that order.

Parameters

[in]	xyzq	Borrowed device pointer to at least the retained PSF's atom `float4` records in `[x, y, z, charge]` order.
[in]	reset	Must be `false`; `true` is currently unsupported.
[in]	calcEnergy	Whether to compute and aggregate potential energy.
[in]	calcVirial	Whether to compute virial contributions.

Precondition: The manager is initialized.; xyzq is non-null, device-accessible, and remains valid through completion.

Postcondition: Aggregate force storage is complete before return.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotImplemented if `reset` is `true`.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if any CUDA operation in the three phases fails.
ApoCharmmError	Propagates categorized built-in or subscribed-force failures.

Note: The method does not implicitly rebuild the direct-space neighbor list when reset is false.

◆ calcForcePart1()

void ForceManager::calcForcePart1	(	const bool	reset,
		const bool	calcEnergy,
		const bool	calcVirial
	)

Clears force and requested energy-virial state.

On first use, the method captures and instantiates a CUDA graph that clears the three built-in fixed-point force arrays. Later calls launch the cached graph. Requested energy and virial state is cleared on the component streams, subscribed forces are cleared, and the aggregate stream is synchronized before return.

Parameters

[in]	reset	Must be `false`; neighbor-list reset through this argument is not implemented.
[in]	calcEnergy	Whether energy state will be computed and therefore must be cleared.
[in]	calcVirial	Whether virial state will be computed and therefore must be cleared.

Precondition: The manager is initialized.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotImplemented if `reset` is `true`.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if graph capture, instantiation, launch, force clearing, or synchronization fails.
ApoCharmmError	Propagates a categorized subscribed-force clear failure.

◆ calcForcePart2()

void ForceManager::calcForcePart2	(	const float4 *	xyzq,
		const bool	calcEnergy,
		const bool	calcVirial
	)

Enqueues all built-in and subscribed force calculations.

Bonded, reciprocal, and direct calculations are enqueued on their respective streams. Each subscribed force is then invoked, with its virial flag enabled only when both calcVirial is true and the force declares that it contributes a virial.

Parameters

[in]	xyzq	Borrowed device pointer to at least `getNumAtoms()` `float4` coordinate-charge records.
[in]	calcEnergy	Whether each force should compute energy.
[in]	calcVirial	Whether eligible forces should compute virial.

Precondition: calcForcePart1() has completed for this evaluation.; The manager is initialized and xyzq is valid device storage.

Exceptions

ApoCharmmError Propagates categorized backend, subscribed-force, or CUDA failures.

Note: This phase does not wait for the enqueued calculations to finish.

◆ calcForcePart3()

void ForceManager::calcForcePart3	(	const float4 *	xyzq,
		const bool	calcEnergy,
		const bool	calcVirial
	)

Synchronizes component work and assembles aggregate outputs.

The method clears aggregate force storage, waits for each component and subscribed stream, and adds every fixed-point force into the aggregate double-precision force array. When requested, it converts force storage for virial calculation, computes eligible virials, copies energies to host storage, sums standard and subscribed energy terms on the aggregate stream, and optionally prints the decomposition.

Parameters

[in]	xyzq	Borrowed device pointer to the same coordinate-charge array passed to `calcForcePart2()`.
[in]	calcEnergy	Whether to update aggregate potential-energy state.
[in]	calcVirial	Whether to update virial state.

Precondition: calcForcePart2() has enqueued all component calculations.; The manager is initialized and xyzq remains valid.

Postcondition: Aggregate force storage is complete before return.; If calcEnergy is true, aggregate device energy is complete and all component host energy mirrors have been copied.; If calcVirial is true, requested virial calculations have completed.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::Cuda if synchronization, conversion, aggregation, transfer, or a CUDA launch reports failure.
ApoCharmmError	Propagates categorized subscribed-force failures.

Note: If calcEnergy or calcVirial is false, the corresponding previous output remains observable and must be treated as stale.

◆ checkBoxDimensions()

void ForceManager::checkBoxDimensions ( const std::vector< double > & boxDimensions )

protected

Validates an orthorhombic box-dimension vector.

Parameters

[in] boxDimensions Vector that must contain exactly three finite positive values in angstroms.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if the length is not three or any value is non-finite or not positive.

◆ computeAllChildrenPotentialEnergy()

virtual CudaContainer< double > ForceManager::computeAllChildrenPotentialEnergy ( const float4 * xyzq )

virtual

Rejects child-energy evaluation in the base manager.

Derived composite managers override this extension point.

Parameters

[in] xyzq Proposed device coordinate-charge array.

Returns: The base implementation never returns successfully.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if `xyzq` is null.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime for every non-null `xyzq`, because the base manager does not support child evaluation.

◆ computeFFTGridSize()

std::vector< int > ForceManager::computeFFTGridSize ( void )

protected

Computes automatic even PME FFT grid dimensions.

Each result is the largest even integer not greater than the corresponding box length after truncation to int, with a minimum value of 2. A warning is written to std::cout when a minimum is applied.

Returns: A new three-element {nfftx, nffty, nfftz} vector of dimensionless grid sizes.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if the stored box vector is not exactly three finite positive values.
std::bad_alloc	If return-vector allocation fails.

◆ getBondedEnergyVirial() [1/2]

CudaEnergyVirial & ForceManager::getBondedEnergyVirial ( void )

Returns mutable bonded energy and virial state.

Returns: A borrowed mutable alias valid until manager destruction.

Warning: Direct mutation can invalidate force-manager energy invariants.

◆ getBondedEnergyVirial() [2/2]

const CudaEnergyVirial & ForceManager::getBondedEnergyVirial ( void ) const

Returns read-only bonded energy and virial state.

Returns: A borrowed read-only alias valid until manager destruction.

Note: The call performs no transfer or synchronization. Host energy values are current only after an energy-producing calculation has copied them.

◆ getBondedForcevalues()

std::shared_ptr< Force< long long int > > ForceManager::getBondedForcevalues ( void )

Returns synchronized bonded fixed-point force storage.

Returns: A copied shared owner of device-resident Force<long long int> storage. Components use structure-of-arrays layout with X at offset 0, Y at stride, and Z at 2 * stride. Raw values must be multiplied by INV_FORCE_SCALE to recover force values in kilocalories per mole per angstrom.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if synchronizing the aggregate stream fails.

◆ getBondedStream()

std::shared_ptr< cudaStream_t > ForceManager::getBondedStream ( void )

Returns the bonded-force CUDA stream holder.

Returns: A copied shared owner of the host cudaStream_t value, or an empty pointer before initialization.

Warning: The manager owns the underlying CUDA stream and destroys it during cleanup regardless of external copies of this shared pointer.

◆ getBoxDimensions() [1/2]

virtual std::vector< double > & ForceManager::getBoxDimensions ( void )

virtual

Returns mutable stored box dimensions.

Returns: A borrowed mutable reference to the manager's box vector.

Warning: Mutating this vector bypasses length and value validation, does not update the float box fields, does not propagate to force backends, and does not reset a neighbor list or FFT grid. Prefer setBoxDimensions().

◆ getBoxDimensions() [2/2]

virtual const std::vector< double > & ForceManager::getBoxDimensions ( void ) const

virtual

Returns read-only stored box dimensions.

Returns: A borrowed read-only reference to exactly three values in [x, y, z] order, in angstroms. Before a box is set, the base constructor stores three sentinel values near -9999.9999.

◆ getChildren() [1/2]

virtual std::vector< std::shared_ptr< ForceManager > > & ForceManager::getChildren ( void )

virtual

Returns mutable child-manager storage.

Returns: A borrowed mutable reference to the base manager's child vector.

Warning: Direct mutation bypasses addForceManager() and can make isComposite() disagree with the stored children.

◆ getChildren() [2/2]

virtual const std::vector< std::shared_ptr< ForceManager > > & ForceManager::getChildren ( void ) const

virtual

Returns read-only child-manager storage.

Returns: A borrowed read-only reference to the base manager's child vector. The vector is empty unless modified through the mutable accessor or by a derived implementation.

◆ getContext()

std::shared_ptr< CharmmContext > ForceManager::getContext ( void )

Returns the associated CharmmContext when it is still alive.

Returns: A newly acquired shared owner of the associated context, or an empty std::shared_ptr when the weak association is unset or expired.

◆ getCtofnb()

float ForceManager::getCtofnb ( void ) const

Returns the stored inner switching distance exposed as ctofnb.

Returns: Distance in angstroms.

◆ getCtonnb()

float ForceManager::getCtonnb ( void ) const

Returns the stored outer switching distance exposed as ctonnb.

Returns: Distance in angstroms.

◆ getCutoff()

float ForceManager::getCutoff ( void ) const

Returns the stored pair-list cutoff.

Returns: Cutoff distance in angstroms.

◆ getDirectEnergyVirial() [1/2]

CudaEnergyVirial & ForceManager::getDirectEnergyVirial ( void )

Returns mutable direct-space energy and virial state.

Returns: A borrowed mutable alias valid until manager destruction.

Warning: Direct mutation can invalidate force-manager energy invariants.

◆ getDirectEnergyVirial() [2/2]

const CudaEnergyVirial & ForceManager::getDirectEnergyVirial ( void ) const

Returns read-only direct-space energy and virial state.

Returns: A borrowed read-only alias valid until manager destruction.

Note: The call performs no transfer or synchronization.

◆ getDirectForcevalues()

std::shared_ptr< Force< long long int > > ForceManager::getDirectForcevalues ( void )

Returns synchronized direct-space fixed-point force storage.

Returns: A copied shared owner with the same layout and scaling as getBondedForcevalues().

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if synchronization fails.

◆ getDirectStream()

std::shared_ptr< cudaStream_t > ForceManager::getDirectStream ( void )

Returns the direct-force CUDA stream holder.

Returns: A copied shared owner of the host cudaStream_t value, or an empty pointer before initialization.

Warning: The manager owns the underlying CUDA stream.

◆ getEnergyComponents()

std::map< std::string, double > ForceManager::getEnergyComponents ( void )

Returns the current host-side energy decomposition.

The returned map contains the keys bond, angle, ureyb, dihe, imdihe, cmap, ewks, ewse, ewex, elec, vdw, and user. user is the sum of the default energy component from every subscribed energy-virial object. Values use kilocalories per mole.

This method reads existing host mirrors. It does not copy energy values from the device and does not synchronize a CUDA stream.

Returns: A new map containing copied energy labels and values.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
std::bad_alloc	If map or string allocation fails.

Precondition: An energy-producing force calculation has completed if current values are required.

◆ getFFTGrid()

std::vector< int > ForceManager::getFFTGrid ( void ) const

Returns the three stored PME FFT grid dimensions.

Returns: A new {nfftx, nffty, nfftz} vector of dimensionless grid sizes. Before an explicit grid or successful initialization, each value is -1.

◆ getForceManagerStream()

std::shared_ptr< cudaStream_t > ForceManager::getForceManagerStream ( void )

Returns the aggregate-force CUDA stream holder.

Returns: A copied shared owner of the host cudaStream_t value, or an empty pointer before initialization.

Warning: The manager owns the underlying CUDA stream.

◆ getForces()

virtual std::shared_ptr< Force< double > > ForceManager::getForces ( void )

virtual

Returns the aggregate double-precision force storage.

This is an aliasing API for getTotalForcevalues().

Returns: A copied shared owner of the same Force<double> object returned by getTotalForcevalues().

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if synchronization fails.

◆ getForceStride()

int ForceManager::getForceStride ( void ) const

Returns the component stride of aggregate force storage.

Returns: Number of double elements between corresponding X, Y, and Z components. The value is dimensionless and may exceed the atom count due to alignment.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.

◆ getKappa()

float ForceManager::getKappa ( void ) const

Returns the stored Ewald splitting parameter.

Returns: Kappa in inverse angstroms.

◆ getPeriodicBoundaryCondition()

PBC ForceManager::getPeriodicBoundaryCondition ( void ) const

Returns the stored periodic boundary condition.

Returns: Current PBC value.

◆ getPmeSplineOrder()

int ForceManager::getPmeSplineOrder ( void ) const

Returns the PME interpolation spline order.

Returns: Positive dimensionless spline order; the default is 4.

◆ getPotentialEnergies()

virtual float ForceManager::getPotentialEnergies ( void )

virtual

Returns the current standard potential-energy sum on the host.

The current implementation copies the bonded, reciprocal, and direct energy-virial objects to host storage, synchronizes the aggregate stream, and sums bond, angle, ureyb, dihe, imdihe, ewks, ewse, ewex, elec, and vdw.

Returns: The listed energy-term sum, narrowed to float, in kilocalories per mole.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if a device-to-host copy or stream synchronization fails.

Warning: The current implementation omits the cmap term and all subscribed-force energies. It is therefore not equivalent to the one-element total produced by calcForce(..., calcEnergy = true, ...).

◆ getPotentialEnergy()

virtual CudaContainer< double > & ForceManager::getPotentialEnergy ( void )

virtual

Returns aggregate potential-energy storage.

Returns: A borrowed mutable alias of a one-element CudaContainer<double> in kilocalories per mole.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.

Note: The current device value is updated only when calcForce() is called with calcEnergy == true. The host mirror is transferred only by code that explicitly requests a transfer or prints the decomposition.; This accessor performs no synchronization or transfer.

◆ getPrm()

std::shared_ptr< CharmmParameters > ForceManager::getPrm ( void )

Returns the retained parameter set.

Returns: A copied shared owner of the current parameter set, or an empty pointer when no parameters have been set. The returned owner may outlive the manager.

◆ getPsf()

virtual std::shared_ptr< CharmmPSF > ForceManager::getPsf ( void )

virtual

Returns the retained PSF.

Returns: A copied shared owner of the current PSF, or an empty pointer when no PSF has been set. The returned owner may outlive the manager.

◆ getReciprocalEnergyVirial() [1/2]

CudaEnergyVirial & ForceManager::getReciprocalEnergyVirial ( void )

Returns mutable reciprocal energy and virial state.

Returns: A borrowed mutable alias valid until manager destruction.

Warning: Direct mutation can invalidate force-manager energy invariants.

◆ getReciprocalEnergyVirial() [2/2]

const CudaEnergyVirial & ForceManager::getReciprocalEnergyVirial ( void ) const

Returns read-only reciprocal energy and virial state.

Returns: A borrowed read-only alias valid until manager destruction.

Note: The call performs no transfer or synchronization.

◆ getReciprocalForcevalues()

std::shared_ptr< Force< long long int > > ForceManager::getReciprocalForcevalues ( void )

Returns synchronized reciprocal fixed-point force storage.

Returns: A copied shared owner with the same layout and scaling as getBondedForcevalues().

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if synchronization fails.

◆ getReciprocalStream()

std::shared_ptr< cudaStream_t > ForceManager::getReciprocalStream ( void )

Returns the reciprocal-force CUDA stream holder.

Returns: A copied shared owner of the host cudaStream_t value, or an empty pointer before initialization.

Warning: The manager owns the underlying CUDA stream.

◆ getShakeAtoms() [1/2]

CudaContainer< int4 > & ForceManager::getShakeAtoms ( void )

Returns mutable SHAKE atom-index records.

Returns: A borrowed mutable alias with the layout documented by the const overload.

Warning: Direct mutation bypasses topology validation and can make host/device constraint state inconsistent with the PSF.

◆ getShakeAtoms() [2/2]

const CudaContainer< int4 > & ForceManager::getShakeAtoms ( void ) const

Returns read-only SHAKE atom-index records.

Each int4 record represents one heavy-atom-centered constrained group: (heavy, hydrogen1, hydrogen2, hydrogen3). Unused hydrogen positions are -1. The container is populated by initialize() and may be empty.

Returns: A borrowed read-only alias of manager-owned host/device mirrored storage. It remains valid until the manager is destroyed or the container is reassigned by another initialization.

◆ getShakeParams() [1/2]

CudaContainer< float4 > & ForceManager::getShakeParams ( void )

Returns mutable SHAKE parameter records.

Returns: A borrowed mutable alias with the layout documented by the const overload.

Warning: Direct mutation bypasses mass, topology, and bond-parameter validation.

◆ getShakeParams() [2/2]

const CudaContainer< float4 > & ForceManager::getShakeParams ( void ) const

Returns read-only SHAKE parameter records.

Each float4 contains the solver fields (inverse-heavy-mass, average-mass-field, squared-bond-length, inverse-hydrogen-mass). Reciprocal masses use inverse atomic mass units, the average-mass field uses atomic mass units, and the squared bond length uses square angstroms. The representation is solver-internal and is not a stable interchange format.

Returns: A borrowed read-only alias of manager-owned host/device mirrored storage. It remains valid until the manager is destroyed or the container is reassigned by another initialization.

◆ getTotalForcevalues()

std::shared_ptr< Force< double > > ForceManager::getTotalForcevalues ( void )

Returns synchronized aggregate double-precision force storage.

Returns: A copied shared owner of device-resident Force<double> storage using structure-of-arrays layout and force units of kilocalories per mole per angstrom.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if synchronization fails.

◆ getVdwType()

int ForceManager::getVdwType ( void ) const

Returns the native van der Waals model code.

Returns: Integer model code in [1, 6] for manager state created through the validated setter.

◆ getVirial()

virtual CudaContainer< double > & ForceManager::getVirial ( void )

virtual

Sums standard and eligible subscribed virial contributions.

The method obtains the bonded, reciprocal, and direct nine-element virial arrays, transfers them to the host, halves the reciprocal contribution for PBC::P21, adds subscribed virials whose force type reports contributesVirial, and transfers the aggregate back to the device.

Returns: A borrowed mutable alias of a nine-element CudaContainer<double>. Values use energy units of kilocalories per mole. Both host and device representations contain the aggregate on successful return.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the manager is not initialized.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if a virial copy or transfer fails.

Note: The public component-to-matrix mapping and sign convention are not established by the current repository; see the unresolved documentation question in the ForceManager documentation work item.

◆ hasCharmmContext()

bool ForceManager::hasCharmmContext ( void ) const

Reports whether the associated CharmmContext is still alive.

Returns: true when the stored weak reference is not expired; otherwise false.

Note: The result can become stale immediately if another thread releases the final context owner. ForceManager provides no internal locking.

◆ initialize()

virtual void ForceManager::initialize ( void )

virtual

Initializes all native force-evaluation state.

Initialization validates required collaborators and configuration, selects an automatic FFT grid when any stored FFT dimension is not positive, and constructs resources in this order:

bonded stream, lists, coefficients, fixed-point force storage, and bonded backend;
reciprocal stream, fixed-point force storage, and PME reciprocal backend;
direct stream, exclusions, neighbor-list state, fixed-point force storage, and PME direct backend;
every force already registered through subscribe();
aggregate stream and double-precision force storage;
one-element aggregate potential-energy storage; and
SHAKE atom and parameter records.

The method performs a device-wide synchronization before creating the aggregate potential-energy container and marks the manager initialized only after every phase succeeds.

Precondition: A non-null PSF and parameter set have been installed.; Three finite positive box dimensions have been set.; The pair-list cutoff is positive and does not exceed half the X box length.

Postcondition: On success, isInitialized() returns true; all four native streams and force arrays are allocated; and already subscribed forces have received the atom count and box.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::NotInitialized if the PSF, parameter set, or box has not been set.
ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if the cutoff is invalid for the X box length or automatic-grid validation fails.
ApoCharmmError	With code ApoCharmmErrorCode::Runtime if the PSF atom count is not positive or a topology/parameter operation reports a runtime failure.
ApoCharmmError	With code ApoCharmmErrorCode::Cuda if CUDA stream creation, force allocation, backend setup, transfer, or synchronization fails.
std::bad_alloc	If native object or container allocation fails.

Warning: Initialization is not transactional. Failure can leave partially allocated resources while isInitialized() remains false.; Repeated initialization of the same instance is not a supported rebuild mechanism in the current implementation.

◆ initializeHolonomicConstraintsVariables()

void ForceManager::initializeHolonomicConstraintsVariables ( void )

protected

Builds GPU SHAKE records from PSF bonds and parameter data.

Hydrogen-containing bonds are grouped by heavy atom, except the currently excluded OT-HT and hydrogen-hydrogen cases. Each selected group creates one int4 atom record and one float4 parameter record as documented by the public SHAKE accessors. The generated vectors are assigned to m_ShakeAtoms and m_ShakeParams, which copies their contents into the corresponding CUDA containers.

Precondition: m_Psf and m_Prm are non-null and describe compatible atom, topology, mass, atom-type, and bond-parameter data.

Postcondition: SHAKE containers contain one record per selected heavy-atom group.

Exceptions

ApoCharmmError	Propagates categorized PSF, parameter, container, or CUDA failures.
std::bad_alloc	If grouping or record allocation fails.

Warning: The current implementation assumes at most three selected hydrogens per heavy atom and non-empty atom-type strings.

◆ isComposite()

virtual bool ForceManager::isComposite ( void ) const

virtual

Reports whether this manager is composite.

Returns: false for the base ForceManager.

◆ isInitialized()

virtual bool ForceManager::isInitialized ( void ) const

virtual

Reports whether native force initialization completed.

Returns: true only after initialize() reaches its successful final assignment; otherwise false.

Note: A false result does not imply that no partial CUDA resources were allocated by an earlier failed initialization.

◆ resetNeighborList()

virtual void ForceManager::resetNeighborList ( const float4 * xyzq )

virtual

Rebuilds the direct-space neighbor list for current coordinates.

Parameters

[in] xyzq Borrowed device pointer to at least the retained PSF's atom float4 records in [x, y, z, charge] order. Coordinates are in angstroms and charges are in elementary-charge units.

Precondition: The manager is initialized.; xyzq is non-null, device-accessible, and remains valid until the direct backend has completed its work.

Exceptions

ApoCharmmError Propagates a categorized direct-backend or CUDA failure.

Note: This method performs no explicit manager-level validation or stream synchronization.

◆ setBoxDimensions()

virtual void ForceManager::setBoxDimensions ( const std::vector< double > & size )

virtual

Sets the orthorhombic box dimensions.

The three values are copied into the manager's double-precision box vector and narrowed to the float scalar fields used by the native force backends. Existing bonded, reciprocal, direct, and subscribed force objects receive the new box in that order.

This call does not recompute an automatic FFT grid, reset the direct-space neighbor list, or clear the initialized flag.

Parameters

[in] size Exactly three finite positive lengths in [x, y, z] order, in angstroms.

Postcondition: On successful return, getBoxDimensions() equals size.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if `size` does not contain exactly three values, or if any value is non-finite or not positive.
ApoCharmmError	Propagates a categorized error from an already constructed native or subscribed force receiving the box update.

Warning: Propagation is not transactional. A failure from a downstream force occurs after the manager's stored box has changed and after any earlier force objects have accepted the update.

◆ setContext()

void ForceManager::setContext ( std::shared_ptr< CharmmContext > ctx )

Stores a non-owning association with a CharmmContext.

The manager stores ctx as a std::weak_ptr. Passing nullptr clears the association. This method does not modify the supplied context and does not call CharmmContext::setForceManager().

Parameters

[in] ctx Context whose control block is observed. The pointer may be null and is not retained through shared ownership.

Postcondition: getContext() returns a shared owner when the context is still alive, or an empty pointer after the association is cleared or expires.

◆ setCtofnb()

virtual void ForceManager::setCtofnb ( const float ctofnb )

virtual

Sets the inner nonbonded switching distance exposed as ctofnb.

The current backend forwarding uses this value as the distance at which switching begins.

Parameters

[in] ctofnb Finite positive distance in angstroms.

Postcondition: getCtofnb() returns ctofnb.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if ctofnb is non-finite or not positive.

Note: The implementation does not validate the ordering of ctonnb and ctofnb.

Warning: This setter does not reconfigure an already constructed direct-space backend.

◆ setCtonnb()

virtual void ForceManager::setCtonnb ( const float ctonnb )

virtual

Sets the outer nonbonded switching distance exposed as ctonnb.

The current backend forwarding uses this value as the distance at which the switching function reaches zero.

Parameters

[in] ctonnb Finite positive distance in angstroms.

Postcondition: getCtonnb() returns ctonnb.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if ctonnb is non-finite or not positive.

Note: The implementation does not validate the ordering of ctonnb and ctofnb.

Warning: This setter does not reconfigure an already constructed direct-space backend.

◆ setCutoff()

virtual void ForceManager::setCutoff ( const float cutoff )

virtual

Sets the direct-space pair-list cutoff.

Parameters

[in] cutoff Finite positive distance in angstroms.

Postcondition: getCutoff() returns cutoff.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if cutoff is non-finite or not positive.

Note: initialize() additionally requires this value not to exceed half the X box length.

Warning: This setter does not update an already constructed direct-space backend or neighbor list.

◆ setFFTGrid()

virtual void ForceManager::setFFTGrid	(	const int	nfftx,
		const int	nffty,
		const int	nfftz
	)

virtual

Sets the three PME FFT grid dimensions.

Parameters

[in]	nfftx	Positive dimensionless grid size along X.
[in]	nffty	Positive dimensionless grid size along Y.
[in]	nfftz	Positive dimensionless grid size along Z.

Postcondition: getFFTGrid() returns {nfftx, nffty, nfftz}.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if any dimension is not positive.

Warning: This setter does not rebuild an already constructed reciprocal backend.

◆ setKappa()

virtual void ForceManager::setKappa ( const float kappa )

virtual

Sets the Ewald splitting parameter.

Parameters

[in] kappa Finite non-negative Ewald parameter in inverse angstroms.

Postcondition: getKappa() returns kappa, subject to float representation.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if kappa is non-finite or negative.

Warning: This setter updates stored configuration only. It does not reconfigure an already constructed reciprocal or direct backend.

◆ setPeriodicBoundaryCondition()

virtual void ForceManager::setPeriodicBoundaryCondition ( const PBC pbc )

virtual

Sets the periodic boundary condition.

Parameters

[in] pbc Declared PBC value to retain.

Postcondition: getPeriodicBoundaryCondition() returns pbc.; isInitialized() returns false.

Warning: The native C++ setter does not validate values produced by casting an arbitrary integer to PBC.; Existing CUDA backend state is not deallocated by this call.

◆ setPmeSplineOrder()

virtual void ForceManager::setPmeSplineOrder ( const int pmeSplineOrder )

virtual

Sets the PME interpolation spline order.

Parameters

[in] pmeSplineOrder Positive dimensionless spline order.

Postcondition: getPmeSplineOrder() returns pmeSplineOrder.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if pmeSplineOrder is not positive.

Warning: This setter does not rebuild an already constructed reciprocal backend.

◆ setPrintEnergyDecomposition()

void ForceManager::setPrintEnergyDecomposition ( const bool printEnergyDecomposition = true )

Enables or disables energy-decomposition printing.

When enabled, calcForce() writes standard and subscribed energy components to std::cout whenever calcEnergy is true.

Parameters

[in] printEnergyDecomposition Whether to print energy terms. Omitting the argument enables printing.

Postcondition: The selected flag is used by subsequent energy-producing force calculations.

◆ setPrm()

void ForceManager::setPrm ( std::shared_ptr< CharmmParameters > prm )

Sets the parameter set retained by the manager.

The supplied object is retained through shared ownership and the manager's initialized flag is cleared. Existing CUDA streams, backends, cached graph state, and force arrays are not deallocated or rebuilt by this call.

Parameters

[in] prm Shared owner of a non-null parameter set.

Postcondition: getPrm() shares ownership with prm.; isInitialized() returns false.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if prm is null. The existing parameter set and initialized flag remain unchanged on this validation failure.

Warning: Configure the parameter set before the first initialization.

◆ setPsf()

void ForceManager::setPsf ( std::shared_ptr< CharmmPSF > psf )

Sets the PSF retained by the manager.

The supplied object is retained through shared ownership and the manager's initialized flag is cleared. Existing CUDA streams, backends, cached graph state, and force arrays are not deallocated or rebuilt by this call.

Parameters

[in] psf Shared owner of a non-null PSF.

Postcondition: getPsf() shares ownership with psf.; isInitialized() returns false.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if psf is null. The existing PSF and initialized flag remain unchanged on this validation failure.

Warning: Configure the PSF before the first initialization. The current implementation does not provide a complete in-place backend rebuild after replacing an initialized manager's PSF.

◆ setVdwType()

virtual void ForceManager::setVdwType ( const int vdwType )

virtual

Sets the native van der Waals model code.

Parameters

[in] vdwType Integer model code from VDW_VSH through VDW_DBEXP, inclusive, corresponding to values 1 through 6.

Postcondition: getVdwType() returns vdwType.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if vdwType is outside [1, 6].

Warning: This setter does not rebuild an already constructed direct-space backend.

◆ subscribe()

template<typename ForceType >

void ForceManager::subscribe	(	std::shared_ptr< ForceType >	force,
		const std::string &	forceTag,
		std::shared_ptr< cudaStream_t >	forceStream,
		std::shared_ptr< Force< long long int > >	forceValues,
		std::shared_ptr< CudaEnergyVirial >	energyVirial
	)

inline

Subscribes an additional force and its CUDA resources.

The manager retains shared ownership of force, forceStream, forceValues, and energyVirial. A type-erased ForceView is stored at the same index as those resources and forceTag. Successful operation therefore preserves the invariant that all six subscription vectors have equal length and corresponding indices describe one force.

If the manager is already initialized, force->initialize() is called with the current PSF atom count and box before any manager subscription vector is modified.

Template Parameters

ForceType Concrete force type satisfying the ForceView interface.

Parameters

[in]	force	Shared owner of the non-null force. The exact object address must not already be subscribed.
[in]	forceTag	Non-empty diagnostic and energy-print label. Tags are not required to be unique.
[in]	forceStream	Shared owner of the non-null CUDA stream holder used by this force.
[in]	forceValues	Shared owner of non-null fixed-point device force storage corresponding to `force`.
[in]	energyVirial	Shared owner of non-null energy and virial storage corresponding to `force`.

Postcondition: On success, the manager owns one shared reference to every supplied object and includes the force in box propagation, clearing, force evaluation, force aggregation, energy aggregation, and eligible virial aggregation.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if any shared pointer is null, `forceTag` is empty, or the same force object is already subscribed.
ApoCharmmError	Propagates a categorized error from `ForceType::initialize()` when the manager is already initialized.
std::bad_alloc	If subscription-vector growth fails.

Warning: The supplied stream, force storage, and energy-virial object must belong to force; the manager does not verify this relationship.; Host allocation failure during the sequence of push_back() operations can leave the parallel subscription vectors with different lengths.

◆ unsubscribe() [1/2]

void ForceManager::unsubscribe ( const std::string & forceTag )

inline

Unsubscribes the first force with a matching tag.

Tags are not required to be unique. When multiple subscriptions use the same tag, only the lowest-index match is removed.

Parameters

[in] forceTag Non-empty tag to find.

Postcondition: On success, the matched force and corresponding resource entries are removed from every parallel subscription vector.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if forceTag is empty or no subscription has that tag.

Note: A validation or lookup failure leaves all subscription vectors unchanged.

◆ unsubscribe() [2/2]

template<typename ForceType >

void ForceManager::unsubscribe ( std::shared_ptr< ForceType > force )

inline

Unsubscribes a force by object identity.

The first subscription whose retained object address equals force.get() is removed from every parallel subscription vector. The manager releases its shared references but does not clear or deinitialize the force.

Template Parameters

ForceType Concrete force type previously passed to subscribe().

Parameters

[in] force Shared owner identifying the subscribed object.

Postcondition: On success, the force no longer participates in manager operations. The force and its resources remain alive while any external shared owners remain.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if force is null or its object address is not subscribed.

Note: A validation failure leaves all subscription vectors unchanged.

Member Data Documentation

◆ m_BondedEnergyVirial

CudaEnergyVirial ForceManager::m_BondedEnergyVirial

protected

Built-in energy and virial registries. Their device values are written on separate component streams, while host values are updated only by explicit copies.

◆ m_BondedForceDirty

bool ForceManager::m_BondedForceDirty

protected

Whether the bonded-force backend must be reconstructed before use.

◆ m_BondedForcePtr

std::unique_ptr<CudaBondedForce<long long int, float> > ForceManager::m_BondedForcePtr

protected

Manager-owned built-in CUDA backend objects. They are null before initialization and are replaced by initialize().

◆ m_BondedForceValues

std::shared_ptr<Force<long long int> > ForceManager::m_BondedForceValues

protected

Device-resident fixed-point force arrays for the three built-in force components. Each uses X/Y/Z structure-of-arrays layout and Force<long long int> scaling.

◆ m_BondedStream

std::shared_ptr<cudaStream_t> ForceManager::m_BondedStream

protected

Host allocations containing the bonded, reciprocal, and direct CUDA stream handles. ForceManager owns and explicitly destroys the underlying CUDA streams.

◆ m_BondedVirial

CudaContainer<double> ForceManager::m_BondedVirial

protected

Nine-element virial work arrays for built-in, subscribed, and aggregate contributions. The arrays maintain host and device storage.

◆ m_BoxDimensions

std::vector<double> ForceManager::m_BoxDimensions

protected

Double-precision [x, y, z] orthorhombic box lengths in angstroms.

◆ m_BoxX

float ForceManager::m_BoxX

protected

Float box lengths passed to selected native backends, in angstroms. They duplicate m_BoxDimensions and are updated only by setBoxDimensions().

◆ m_Children

std::vector<std::shared_ptr<ForceManager> > ForceManager::m_Children

protected

Child-manager storage used by derived composite implementations. The base manager leaves it empty and reports isComposite() == false.

◆ m_ClearGraphCreated

bool ForceManager::m_ClearGraphCreated

protected

Cached CUDA graph used to clear the three built-in fixed-point force arrays. m_ClearGraphCreated is the lifecycle discriminator for the graph and executable handles.

◆ m_ComputeDirectSpaceForces

bool ForceManager::m_ComputeDirectSpaceForces

protected

Legacy direct-space computation-selection flag used by specialized manager implementations. The base constructor initializes it to true.

◆ m_Context

std::weak_ptr<CharmmContext> ForceManager::m_Context

protected

Non-owning backlink to the associated context. The context is never kept alive solely by its force manager.

◆ m_Ctofnb

float ForceManager::m_Ctofnb

protected

Inner switching distance in angstroms as currently forwarded to the direct backend; default 10.0.

◆ m_Ctonnb

float ForceManager::m_Ctonnb

protected

Outer switching distance in angstroms as currently forwarded to the direct backend; default 12.0.

◆ m_Cutoff

float ForceManager::m_Cutoff

protected

Direct-space pair-list cutoff in angstroms, corresponding to CHARMM CUTNB; default 14.0.

◆ m_DirectForceDirty

bool ForceManager::m_DirectForceDirty

protected

Whether the direct-space backend must be reconstructed before use.

◆ m_ForceManagerStream

std::shared_ptr<cudaStream_t> ForceManager::m_ForceManagerStream

protected

Host allocation containing the CUDA stream used for force clearing, aggregation, and total-energy kernels.

◆ m_ForcePtrs

std::vector<std::shared_ptr<void> > ForceManager::m_ForcePtrs

protected

Parallel subscription state. For every valid index:

m_ForcePtrs owns the concrete force;
m_ForceViews dispatches to that force;
m_ForceTags stores its label;
m_ForceStreams owns its stream holder;
m_ForceValues owns its fixed-point force storage; and
m_EnergyVirials owns its energy and virial storage.

Successful subscription and unsubscription require all vectors to have equal length.

◆ m_IsInitialized

bool ForceManager::m_IsInitialized

protected

Successful-initialization flag. It changes to true only at the final statement of initialize() and can be cleared by selected collaborator or PBC setters without deallocating existing resources.

◆ m_Kappa

float ForceManager::m_Kappa

protected

Ewald splitting parameter in inverse angstroms; default 0.34.

◆ m_NfftX

int ForceManager::m_NfftX

protected

Dimensionless PME FFT dimensions. The -1 constructor sentinel selects automatic grid generation during initialization.

◆ m_Pbc

PBC ForceManager::m_Pbc

protected

Periodic-boundary mode; default PBC::P1.

◆ m_PmeSplineOrder

int ForceManager::m_PmeSplineOrder

protected

Positive dimensionless PME interpolation spline order; default 4.

◆ m_PrintEnergyDecomposition

bool ForceManager::m_PrintEnergyDecomposition

protected

Selects standard and subscribed energy output to std::cout during an energy-producing force calculation.

◆ m_Prm

std::shared_ptr<CharmmParameters> ForceManager::m_Prm

protected

Shared owner of the force-field parameter set used by initialization.

◆ m_Psf

std::shared_ptr<CharmmPSF> ForceManager::m_Psf

protected

Shared owner of the topology and atom metadata used by initialization.

◆ m_ReciprocalForceDirty

bool ForceManager::m_ReciprocalForceDirty

protected

Whether the reciprocal-space backend must be reconstructed before use.

◆ m_ShakeAtoms

CudaContainer<int4> ForceManager::m_ShakeAtoms

protected

Host/device mirrored SHAKE atom groups. Each int4 stores one heavy atom and up to three hydrogen atom indices.

◆ m_ShakeParams

CudaContainer<float4> ForceManager::m_ShakeParams

protected

Host/device mirrored solver parameters corresponding one-to-one with m_ShakeAtoms.

◆ m_TotalForceValues

std::shared_ptr<Force<double> > ForceManager::m_TotalForceValues

protected

Device-resident double-precision aggregate force array. The exact force-versus-energy-gradient sign convention requires separate clarification; the current integration paths consume this object as the manager's force output.

◆ m_TotalPotentialEnergy

CudaContainer<double> ForceManager::m_TotalPotentialEnergy

protected

One-element aggregate potential-energy storage in kilocalories per mole.

◆ m_VdwType

int ForceManager::m_VdwType

protected

Native van der Waals model code; default VDW_VFSW.

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ForceManager() [1/3]

◆ ForceManager() [2/3]

◆ ForceManager() [3/3]

◆ ~ForceManager()

Member Function Documentation

◆ addForceManager()

◆ addPrm() [1/2]

◆ addPrm() [2/2]

◆ addPsf()

◆ calcForce()

◆ calcForcePart1()

◆ calcForcePart2()

◆ calcForcePart3()

◆ checkBoxDimensions()

◆ computeAllChildrenPotentialEnergy()

◆ computeFFTGridSize()

◆ getBondedEnergyVirial() [1/2]

◆ getBondedEnergyVirial() [2/2]

◆ getBondedForcevalues()

◆ getBondedStream()

◆ getBoxDimensions() [1/2]

◆ getBoxDimensions() [2/2]

◆ getChildren() [1/2]

◆ getChildren() [2/2]

◆ getContext()

◆ getCtofnb()

◆ getCtonnb()

◆ getCutoff()

◆ getDirectEnergyVirial() [1/2]

◆ getDirectEnergyVirial() [2/2]

◆ getDirectForcevalues()

◆ getDirectStream()

◆ getEnergyComponents()

◆ getFFTGrid()

◆ getForceManagerStream()

◆ getForces()

◆ getForceStride()

◆ getKappa()

◆ getPeriodicBoundaryCondition()

◆ getPmeSplineOrder()

◆ getPotentialEnergies()

◆ getPotentialEnergy()

◆ getPrm()

◆ getPsf()

◆ getReciprocalEnergyVirial() [1/2]

◆ getReciprocalEnergyVirial() [2/2]

◆ getReciprocalForcevalues()

◆ getReciprocalStream()

◆ getShakeAtoms() [1/2]

◆ getShakeAtoms() [2/2]

◆ getShakeParams() [1/2]

◆ getShakeParams() [2/2]

◆ getTotalForcevalues()

◆ getVdwType()

◆ getVirial()

◆ hasCharmmContext()

◆ initialize()

◆ initializeHolonomicConstraintsVariables()

◆ isComposite()

◆ isInitialized()

◆ resetNeighborList()

◆ setBoxDimensions()

◆ setContext()

◆ setCtofnb()

◆ setCtonnb()

◆ setCutoff()

◆ setFFTGrid()

◆ setKappa()

◆ setPeriodicBoundaryCondition()

◆ setPmeSplineOrder()

◆ setPrintEnergyDecomposition()

◆ setPrm()

◆ setPsf()

◆ setVdwType()

◆ subscribe()