Propagates constant-temperature dynamics with Langevin noise. More...

#include <CudaLangevinThermostatIntegrator.h>

Inheritance diagram for CudaLangevinThermostatIntegrator:

Public Member Functions
	CudaLangevinThermostatIntegrator (const double timeStep)
	Constructs an unattached Langevin thermostat integrator.

	~CudaLangevinThermostatIntegrator (void) noexcept override
	Destroys the thermostat and its RNG-state allocation.

void	setReferenceTemperature (const double referenceTemperature)
	Sets the reference temperature.

void	setThermostatFriction (const double thermostatFriction)
	Sets the thermostat friction coefficient.

void	setThermostatRngSeed (const std::uint64_t seed)
	Sets the thermostat RNG seed.

void	setRngSequencePos (const unsigned long long int sequencePos)
	Sets the thermostat RNG sequence position.

void	setRngStates (const std::string &rngStateString)
	Restores serialized per-atom RNG states.

void	resetAverageTemperature (void)
	Resets both running-temperature values and their sample count.

double	getReferenceTemperature (void) const
	Returns the reference temperature.

double	getThermostatFriction (void) const
	Returns the thermostat friction coefficient.

std::uint64_t	getThermostatRngSeed (void) const
	Returns the thermostat RNG seed.

unsigned long long int	getRngSequencePos (void) const
	Returns the recorded thermostat RNG sequence position.

std::string	getRngStates (void) const
	Copies the current per-atom RNG states to a serialized string.

int	getAverageWindowSize (void) const
	Returns the number of samples in the running average.

const CudaContainer< double > &	getKineticEnergy (void) const
	Returns both kinetic-energy estimators.

const CudaContainer< double > &	getAverageTemperature (void) const
	Returns both running-temperature estimators.

CudaContainer< double > &	getKineticEnergy (void)
	Returns mutable kinetic-energy storage.

CudaContainer< double > &	getAverageTemperature (void)
	Returns mutable running-temperature storage.

double	getInstantaneousTemperature (void)
	Computes the instantaneous three-point temperature.

Public Member Functions inherited from CudaIntegrator
	CudaIntegrator (void)
	Constructs an unattached base integrator with no time step.

	CudaIntegrator (const double timeStep)
	Constructs an unattached integrator with a time step.

	CudaIntegrator (const double timeStep, const int debugPrintFrequency)
	Constructs an integrator with a time step and debug interval.

virtual	~CudaIntegrator (void) noexcept
	Destroys the base integrator and its CUDA streams.

double	getTimeStep (void) const
	Returns the public integrator time step.

void	setTimeStep (const double dt)
	Sets the public integrator time step.

virtual void	setCharmmContext (std::shared_ptr< CharmmContext > ctx) final
	Attaches a context and initializes concrete integrator state.

const std::shared_ptr< CharmmContext >	getCharmmContext (void) const
	Returns the retained context from a const integrator.

std::shared_ptr< CharmmContext >	getCharmmContext (void)
	Returns the retained context from a mutable integrator.

virtual void	initialize (void) final
	Reinitializes concrete integrator state from the attached context.

virtual void	initializeFromRestartFile (const std::filesystem::path &rstFilePath) final
	Initializes concrete integrator state from a restart file.

virtual void	propagateOneStep (void) final
	Propagates one concrete dynamics step without base-loop bookkeeping.

void	propagate (const int numSteps)
	Propagates dynamics and invokes scheduled subscriber updates.

void	setDebugPrintFrequency (const int freq)
	Sets the concrete-integrator debug-calculation interval.

void	setNonbondedListUpdateFrequency (const int freq)
	Sets the nonbonded neighbor-list update interval.

void	subscribe (std::shared_ptr< Subscriber > sub)
	Attaches one subscriber and caches its reporting interval.

void	subscribe (const std::vector< std::shared_ptr< Subscriber > > &sublist)
	Attaches subscribers sequentially in vector order.

void	unsubscribe (std::shared_ptr< Subscriber > sub)
	Removes one subscriber and its cached reporting interval.

void	unsubscribe (const std::vector< std::shared_ptr< Subscriber > > &sublist)
	Removes subscribers sequentially in vector order.

const std::vector< std::shared_ptr< Subscriber > > &	getSubscribers (void) const
	Returns the attached subscriber array.

std::vector< std::shared_ptr< Subscriber > > &	getSubscribers (void)
	Returns mutable access to the attached subscriber array.

const std::vector< int > &	getReportFreqList (void) const
	Returns the cached subscriber-frequency array.

std::vector< int > &	getReportFreqList (void)
	Returns mutable access to cached subscriber frequencies.

void	setRemoveCenterOfMassFrequency (const int freq)
	Sets the center-of-mass-removal interval.

const CudaContainer< double4 > &	getCoordsDelta (void) const
	Returns the current half-step displacement container.

CudaContainer< double4 > &	getCoordsDelta (void)
	Returns mutable current half-step displacement storage.

const CudaContainer< double4 > &	getCoordsDeltaPrevious (void) const
	Returns the previous half-step displacement container.

CudaContainer< double4 > &	getCoordsDeltaPrevious (void)
	Returns mutable previous half-step displacement storage.

virtual std::map< std::string, std::string >	getIntegratorDescriptors (void)
	Returns key/value descriptors for the concrete integrator.

int	getCurrentPropagatedStep (void) const
	Returns the wrapped completed-step counter.

unsigned long long int	getTotNumSteps (void) const
	Returns the total number of requested propagation steps.

int	getNumSteps (void) const
	Returns the most recently requested propagation length.

Protected Member Functions
void	initializeImpl (void) override
	Allocates and initializes thermostat state from the context.

void	initializeFromRestartFileImpl (const std::filesystem::path &rstFilePath) override
	Restores thermostat displacement and RNG state from a restart file.

void	propagateOneStepImpl (void) override
	Executes one synchronized stochastic thermostat step.

void	setRngStateData (const unsigned long long int position, const std::vector< curandStatePhilox4_32_10_t > &states)
	Copies decoded RNG state to device storage.

void	initializeRng (void)
	Allocates and initializes one RNG state per attached-context atom.

void	removeCenterOfMassMotion (void)
	Removes mass-weighted center-of-mass displacement.

void	alloc (const int n)
	Allocates raw device storage for `n` RNG states.

void	dealloc (void)
	Releases raw RNG-state storage through the checked native helper.

Protected Member Functions inherited from CudaIntegrator
void	requirePropagationReady (void) const
	Validates shared state required for propagation.

void	reportIfNeeded (const int istep)
	Invokes subscribers scheduled for one local propagation step.

Protected Attributes
double	m_ReferenceTemperature
	Stores the reference temperature in kelvin.

double	m_ThermostatFriction
	Stores the public friction coefficient in inverse picoseconds.

double	m_ThermostatGamma
	Stores the dimensionless friction accumulated over one time step.

std::uint64_t	m_Seed
	Stores the dimensionless 64-bit Philox seed.

unsigned long long int	m_RngSequencePos
	Stores the recorded dimensionless Philox sequence position.

curandStatePhilox4_32_10_t *	m_RngStates
	Owns one raw device Philox state per context atom.

int	m_AverageWindowSize
	Stores the number of samples accumulated into running averages.

CudaContainer< double >	m_KineticEnergy
	Stores two kinetic-energy estimators in kilocalories per mole.

CudaContainer< double >	m_KineticEnergyPartialSums
	Stores per-block partial sums for both kinetic estimators.

CudaContainer< double >	m_AverageTemperature
	Stores two running-temperature estimators in kelvin.

Protected Attributes inherited from CudaIntegrator
double	m_TimeStep
	Stores the internal time step in AKMA time.

double	m_Timfac
	Stores the picoseconds-to-AKMA-time conversion factor.

int	m_DebugPrintFrequency
	Stores the non-negative concrete debug-calculation interval.

std::shared_ptr< CharmmContext >	m_Context
	Retains the context attached to this integrator.

int	m_StepsSinceNeighborListUpdate
	Stores the current per-call neighbor-list scheduling counter.

int	m_CurrentPropagatedStep
	Stores the wrapped number of completed base-loop steps.

unsigned long long int	m_TotNumSteps
	Stores the accumulated number of requested propagation steps.

int	m_NumSteps
	Stores the most recently accepted propagation request length.

std::shared_ptr< CudaHolonomicConstraint >	m_HolonomicConstraint
	Retains the optional holonomic-constraint helper.

CudaContainer< double4 >	m_CoordsRef
	Stores per-atom reference coordinates used by concrete steps.

CudaContainer< double4 >	m_CoordsDelta
	Stores current half-step displacements.

CudaContainer< double4 >	m_CoordsDeltaPrevious
	Stores previous half-step displacements.

std::shared_ptr< cudaStream_t >	m_IntegratorStream
	Owns the primary CUDA stream used by concrete integrator work.

std::shared_ptr< cudaStream_t >	m_IntegratorMemcpyStream
	Owns a reserved CUDA memcpy stream.

bool	m_UsingHolonomicConstraints
	Stores the constraint setting captured during context attachment.

std::vector< std::shared_ptr< Subscriber > >	m_Subscribers
	Retains subscribers in callback order.

std::vector< int >	m_ReportFreqList
	Stores the frequency snapshot for each attached subscriber.

int	m_NonbondedListUpdateFrequency
	Stores the positive nonbonded-list update interval in steps.

int	m_RemoveCenterOfMassFrequency
	Stores the positive center-of-mass-removal interval in steps.

std::string	m_IntegratorTypeName
	Stores the concrete integrator label used by subscribers.

Detailed Description

Propagates constant-temperature dynamics with Langevin noise.

The integrator maintains one Philox RNG state per context atom, applies stochastic position updates, enforces configured holonomic constraints, derives velocities from corrected displacement history, and accumulates two kinetic and temperature estimators.

Warning: Treat the class as non-copyable. It owns a raw device RNG-state allocation in addition to the base CUDA streams.

See also: cuda_integrators

Constructor & Destructor Documentation

◆ CudaLangevinThermostatIntegrator()

CudaLangevinThermostatIntegrator::CudaLangevinThermostatIntegrator ( const double timeStep )

Constructs an unattached Langevin thermostat integrator.

Parameters

[in] timeStep Finite positive time step in picoseconds.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `timeStep` is non-finite or not positive.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if stream or fixed-state allocation fails.
std::bad_alloc	If host or stream-owner allocation fails.
std::system_error	If the platform random source used for the initial seed fails.

Postcondition: The reference temperature is 300 K, friction is zero, a seed has been sampled, the sequence position is zero, and running averages are zero.

◆ ~CudaLangevinThermostatIntegrator()

CudaLangevinThermostatIntegrator::~CudaLangevinThermostatIntegrator ( void )

overridenoexcept

Destroys the thermostat and its RNG-state allocation.

CUDA cleanup failures are discarded and no exception escapes.

Member Function Documentation

◆ alloc()

void CudaLangevinThermostatIntegrator::alloc ( const int n )

protected

Allocates raw device storage for n RNG states.

Parameters

[in] n Number of per-atom states.

◆ getAverageTemperature() [1/2]

CudaContainer< double > & CudaLangevinThermostatIntegrator::getAverageTemperature ( void )

Returns mutable running-temperature storage.

Returns: Borrowed mutable alias to the two-element container.

Warning: Preserve the two-element shape and host/device coherence.

◆ getAverageTemperature() [2/2]

const CudaContainer< double > & CudaLangevinThermostatIntegrator::getAverageTemperature ( void ) const

Returns both running-temperature estimators.

Returns: Borrowed const alias to a two-element container in kelvin with the same element order as getKineticEnergy().

◆ getAverageWindowSize()

int CudaLangevinThermostatIntegrator::getAverageWindowSize ( void ) const

Returns the number of samples in the running average.

Returns: A non-negative dimensionless count.

◆ getInstantaneousTemperature()

double CudaLangevinThermostatIntegrator::getInstantaneousTemperature ( void )

Computes the instantaneous three-point temperature.

Returns: Kinetic-energy element 0 converted to kelvin.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if no context is attached.
ApoCharmmError	With code `ApoCharmmErrorCode::Runtime` if the kinetic-energy container does not contain exactly two elements.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if the kinetic energy cannot be transferred to the host.

◆ getKineticEnergy() [1/2]

CudaContainer< double > & CudaLangevinThermostatIntegrator::getKineticEnergy ( void )

Returns mutable kinetic-energy storage.

Returns: Borrowed mutable alias to the two-element container.

Warning: Preserve the two-element shape and host/device coherence.

◆ getKineticEnergy() [2/2]

const CudaContainer< double > & CudaLangevinThermostatIntegrator::getKineticEnergy ( void ) const

Returns both kinetic-energy estimators.

Returns: Borrowed const alias to a two-element container in kilocalories per mole. Element 0 is the three-point estimator and element 1 is the on-step estimator.

◆ getReferenceTemperature()

double CudaLangevinThermostatIntegrator::getReferenceTemperature ( void ) const

Returns the reference temperature.

Returns: The stored temperature in kelvin.

◆ getRngSequencePos()

unsigned long long int CudaLangevinThermostatIntegrator::getRngSequencePos ( void ) const

Returns the recorded thermostat RNG sequence position.

Returns: The dimensionless Philox position. Successful propagation advances this value by four per step.

◆ getRngStates()

std::string CudaLangevinThermostatIntegrator::getRngStates ( void ) const

Copies the current per-atom RNG states to a serialized string.

Returns: A newly allocated opaque string containing the recorded sequence position and one Philox state per context atom.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if no context is attached or RNG state has not been initialized.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if stream synchronization or device-to-host transfer fails.
std::bad_alloc	If the host state vector or result string cannot be allocated.

Note: The method synchronizes the primary integrator stream before copying.

◆ getThermostatFriction()

double CudaLangevinThermostatIntegrator::getThermostatFriction ( void ) const

Returns the thermostat friction coefficient.

Returns: The configured value in inverse picoseconds.

◆ getThermostatRngSeed()

std::uint64_t CudaLangevinThermostatIntegrator::getThermostatRngSeed ( void ) const

Returns the thermostat RNG seed.

Returns: The dimensionless 64-bit seed.

◆ initializeFromRestartFileImpl()

void CudaLangevinThermostatIntegrator::initializeFromRestartFileImpl ( const std::filesystem::path & rstFilePath )

overrideprotectedvirtual

Restores thermostat displacement and RNG state from a restart file.

Parameters

[in] rstFilePath Borrowed restart-file path. The path is not canonicalized or retained.

Reimplemented from CudaIntegrator.

◆ initializeRng()

void CudaLangevinThermostatIntegrator::initializeRng ( void )

protected

Allocates and initializes one RNG state per attached-context atom.

The method does nothing before context attachment.

◆ resetAverageTemperature()

void CudaLangevinThermostatIntegrator::resetAverageTemperature ( void )

Resets both running-temperature values and their sample count.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::Cuda if the device array cannot be reset.

◆ setReferenceTemperature()

void CudaLangevinThermostatIntegrator::setReferenceTemperature ( const double referenceTemperature )

Sets the reference temperature.

Parameters

[in] referenceTemperature Finite non-negative temperature in kelvin.

Exceptions

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

◆ setRngSequencePos()

void CudaLangevinThermostatIntegrator::setRngSequencePos ( const unsigned long long int sequencePos )

Sets the thermostat RNG sequence position.

Parameters

[in] sequencePos Dimensionless Philox sequence position.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::Cuda if an attached context requires RNG allocation or initialization and CUDA work fails.

Postcondition: The current seed is preserved. With an attached context, one state per atom is regenerated and advanced to sequencePos.

◆ setRngStateData()

void CudaLangevinThermostatIntegrator::setRngStateData	(	const unsigned long long int	position,
		const std::vector< curandStatePhilox4_32_10_t > &	states
	)

protected

Copies decoded RNG state to device storage.

Parameters

[in]	position	Dimensionless sequence position to store.
[in]	states	Borrowed contiguous host states copied during the call.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::Cuda if allocation or host-to-device transfer fails.

◆ setRngStates()

void CudaLangevinThermostatIntegrator::setRngStates ( const std::string & rngStateString )

Restores serialized per-atom RNG states.

Parameters

[in] rngStateString Borrowed opaque string produced by getRngStates().

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if no context is attached.
ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if the decoded state count does not equal the context atom count.
ApoCharmmError	With code `ApoCharmmErrorCode::Runtime` if the string cannot be decoded.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if device allocation or host-to-device transfer fails.

Postcondition: Both the encoded position and every decoded state have been copied into the integrator.

◆ setThermostatFriction()

void CudaLangevinThermostatIntegrator::setThermostatFriction ( const double thermostatFriction )

Sets the thermostat friction coefficient.

Parameters

[in] thermostatFriction Finite non-negative friction in inverse picoseconds.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `thermostatFriction` is non-finite or negative.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if changing the value triggers reinitialization and CUDA work fails.
std::bad_alloc	If triggered reinitialization cannot allocate work storage.

Postcondition: The dimensionless per-step coefficient is recomputed from the public time step.

Note: When a context is attached and no propagation steps have yet been requested, this method immediately reruns concrete initialization.

◆ setThermostatRngSeed()

void CudaLangevinThermostatIntegrator::setThermostatRngSeed ( const std::uint64_t seed )

Sets the thermostat RNG seed.

Parameters

[in] seed Dimensionless 64-bit seed.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::Cuda if an attached context requires RNG allocation or initialization and CUDA work fails.

Postcondition: The existing sequence position is preserved. With an attached context, one state per atom is regenerated from the new seed and that position.

Member Data Documentation

◆ m_KineticEnergy

CudaContainer<double> CudaLangevinThermostatIntegrator::m_KineticEnergy

protected

Stores two kinetic-energy estimators in kilocalories per mole.

Element 0 is the three-point estimator and element 1 is the on-step estimator.

◆ m_RngStates

curandStatePhilox4_32_10_t* CudaLangevinThermostatIntegrator::m_RngStates

protected

Owns one raw device Philox state per context atom.

The pointer is null before RNG initialization and is released by the non-throwing destructor.

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CudaLangevinThermostatIntegrator()

◆ ~CudaLangevinThermostatIntegrator()

Member Function Documentation

◆ alloc()

◆ getAverageTemperature() [1/2]

◆ getAverageTemperature() [2/2]

◆ getAverageWindowSize()

◆ getInstantaneousTemperature()

◆ getKineticEnergy() [1/2]

◆ getKineticEnergy() [2/2]

◆ getReferenceTemperature()

◆ getRngSequencePos()

◆ getRngStates()

◆ getThermostatFriction()

◆ getThermostatRngSeed()

◆ initializeFromRestartFileImpl()

◆ initializeRng()

◆ resetAverageTemperature()

◆ setReferenceTemperature()

◆ setRngSequencePos()

◆ setRngStateData()

◆ setRngStates()

◆ setThermostatFriction()

◆ setThermostatRngSeed()

Member Data Documentation

◆ m_KineticEnergy

◆ m_RngStates