apoCHARMM 1.0.0
High-performance molecular dynamics simulations on GPUs
 
Loading...
Searching...
No Matches
CudaNoseHooverIntegrator Class Reference

Propagates constant-temperature dynamics with Nose-Hoover coupling. More...

#include <CudaNoseHooverIntegrator.h>

Inheritance diagram for CudaNoseHooverIntegrator:
CudaIntegrator

Public Member Functions

 CudaNoseHooverIntegrator (const double timeStep)
 Constructs an unattached Nose-Hoover integrator.
 
void setReferenceTemperature (const double referenceTemperature)
 Sets the Nose-Hoover reference temperature.
 
void setNoseHooverPistonMass (const double noseHooverPistonMass)
 Sets the scalar Nose-Hoover coupling mass.
 
void setNoseHooverPistonVelocity (const double noseHooverPistonVelocity)
 Sets the current Nose-Hoover extended-variable velocity.
 
void setNoseHooverPistonVelocityPrevious (const double noseHooverPistonVelocityPrevious)
 Sets the previous Nose-Hoover extended-variable velocity.
 
void setNoseHooverPistonForce (const double noseHooverPistonForce)
 Sets the current Nose-Hoover velocity-increment state.
 
void setNoseHooverPistonForcePrevious (const double noseHooverPistonForcePrevious)
 Sets the previous Nose-Hoover velocity-increment state.
 
void setMaxPredictorCorrectorIterations (const int maxPredictorCorrectorIterations)
 Sets the number of Nose-Hoover predictor-corrector iterations.
 
void useOldTemperature (const bool usingOldTemperature)
 Selects the on-step temperature estimator.
 
void resetAverageTemperature (void)
 Resets both running-temperature values and their sample count.
 
double getReferenceTemperature (void) const
 Returns the reference temperature.
 
bool usingOldTemperature (void) const
 Returns the native temperature-estimator selector.
 
const CudaContainer< double > & getNoseHooverPistonMass (void) const
 Returns the scalar coupling-mass container.
 
const CudaContainer< double > & getNoseHooverPistonVelocity (void) const
 Returns the current extended-variable velocity container.
 
const CudaContainer< double > & getNoseHooverPistonVelocityPrevious (void) const
 Returns the previous extended-variable velocity container.
 
const CudaContainer< double > & getNoseHooverPistonForce (void) const
 Returns the current velocity-increment container.
 
const CudaContainer< double > & getNoseHooverPistonForcePrevious (void) const
 Returns the previous velocity-increment container.
 
int getMaxPredictorCorrectorIterations (void) const
 Returns the predictor-corrector iteration count.
 
const CudaContainer< double > & getKineticEnergy (void) const
 Returns both kinetic-energy estimators.
 
const CudaContainer< double > & getAverageTemperature (void) const
 Returns both running-temperature estimators.
 
CudaContainer< double > & getNoseHooverPistonMass (void)
 Returns mutable scalar coupling-mass storage.
 
CudaContainer< double > & getNoseHooverPistonVelocity (void)
 Returns mutable current extended-variable velocity storage.
 
CudaContainer< double > & getNoseHooverPistonVelocityPrevious (void)
 Returns mutable previous extended-variable velocity storage.
 
CudaContainer< double > & getNoseHooverPistonForce (void)
 Returns mutable current velocity-increment storage.
 
CudaContainer< double > & getNoseHooverPistonForcePrevious (void)
 Returns mutable previous velocity-increment storage.
 
CudaContainer< double > & getKineticEnergy (void)
 Returns mutable kinetic-energy storage.
 
CudaContainer< double > & getAverageTemperature (void)
 Returns mutable running-temperature storage.
 
double getInstantaneousTemperature (void)
 Computes the selected instantaneous 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< CharmmContextgetCharmmContext (void) const
 Returns the retained context from a const integrator.
 
std::shared_ptr< CharmmContextgetCharmmContext (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 Nose-Hoover state from the context.
 
void initializeFromRestartFileImpl (const std::filesystem::path &rstFilePath) override
 Restores Nose-Hoover state from a CHARMM-style restart file.
 
void propagateOneStepImpl (void) override
 Executes one synchronized Nose-Hoover propagation step.
 
double computeNoseHooverPistonMass (void)
 Computes the default numeric coupling mass.
 
void removeCenterOfMassMotion (void)
 Removes mass-weighted center-of-mass displacement.
 
- 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.
 
CudaContainer< double > m_NoseHooverPistonMass
 Stores the one-element Nose-Hoover coupling mass.
 
CudaContainer< double > m_NoseHooverPistonVelocity
 Stores the current one-element extended-variable velocity.
 
CudaContainer< double > m_NoseHooverPistonVelocityPrevious
 Stores the previous extended-variable velocity.
 
CudaContainer< double > m_NoseHooverPistonForce
 Stores the current extended-variable velocity increment.
 
CudaContainer< double > m_NoseHooverPistonForcePrevious
 Stores the previous extended-variable velocity increment.
 
CudaContainer< double4 > m_CoordsDeltaPredicted
 Stores one predicted double4 displacement per context atom.
 
int m_MaxPredictorCorrectorIterations
 Stores the positive predictor-corrector iteration count.
 
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.
 
bool m_UsingOldTemperature
 Selects element 1 instead of element 0 for native feedback.
 
- 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< CharmmContextm_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 Nose-Hoover coupling.

The integrator maintains one Nose-Hoover extended variable, two kinetic energy estimators, two running-temperature estimators, and a predictor-corrector displacement buffer. Context attachment initializes the derived state and calculates a default coupling mass when no explicit mass has been supplied.

Warning
Treat the class as non-copyable. Its base owns CUDA streams whose implicit copy semantics are unsafe.
See also
cuda_integrators

Constructor & Destructor Documentation

◆ CudaNoseHooverIntegrator()

CudaNoseHooverIntegrator::CudaNoseHooverIntegrator ( const double  timeStep)

Constructs an unattached Nose-Hoover integrator.

Parameters
[in]timeStepFinite positive time step in picoseconds.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if timeStep is non-finite or not positive.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if stream or fixed-state allocation fails.
std::bad_allocIf host or stream-owner allocation fails.
Postcondition
The reference temperature is 300 K, the maximum predictor-corrector count is three, the old-temperature selector is false, and the running averages are zero.

Member Function Documentation

◆ computeNoseHooverPistonMass()

double CudaNoseHooverIntegrator::computeNoseHooverPistonMass ( void  )
protected

Computes the default numeric coupling mass.

Returns
0.2 times the sum of context atom masses. The exact dimensional convention of the returned extended-system value is not established by the repository.

◆ getAverageTemperature() [1/2]

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

Returns mutable running-temperature storage.

Returns
Borrowed mutable alias to the two-element container.
Warning
Preserve the two-element estimator layout.

◆ getAverageTemperature() [2/2]

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

Returns both running-temperature estimators.

Returns
Borrowed const alias to a two-element container in kelvin. Element 0 corresponds to the three-point estimator and element 1 to the on-step estimator.
Note
The accessor performs no device-to-host transfer.

◆ getInstantaneousTemperature()

double CudaNoseHooverIntegrator::getInstantaneousTemperature ( void  )

Computes the selected instantaneous temperature.

Returns
The selected kinetic-energy estimator converted to kelvin.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::NotInitialized if no context is attached.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if kinetic energy cannot be transferred to the host.
Note
The method selects element 1 when usingOldTemperature() is true and element 0 otherwise.

◆ getKineticEnergy() [1/2]

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

Returns mutable kinetic-energy storage.

Returns
Borrowed mutable alias to the two-element container.
Warning
Preserve the two-element estimator layout.

◆ getKineticEnergy() [2/2]

const CudaContainer< double > & CudaNoseHooverIntegrator::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.
Note
The accessor performs no device-to-host transfer.

◆ getMaxPredictorCorrectorIterations()

int CudaNoseHooverIntegrator::getMaxPredictorCorrectorIterations ( void  ) const

Returns the predictor-corrector iteration count.

Returns
A positive dimensionless iteration count.

◆ getNoseHooverPistonForce() [1/2]

CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonForce ( void  )

Returns mutable current velocity-increment storage.

Returns
Borrowed mutable alias to the one-element container.
Warning
Preserve its one-element shape and host/device coherence.

◆ getNoseHooverPistonForce() [2/2]

const CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonForce ( void  ) const

Returns the current velocity-increment container.

Returns
Borrowed const alias to a one-element integrator-owned container.

◆ getNoseHooverPistonForcePrevious() [1/2]

CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonForcePrevious ( void  )

Returns mutable previous velocity-increment storage.

Returns
Borrowed mutable alias to the one-element container.
Warning
Preserve its one-element shape and host/device coherence.

◆ getNoseHooverPistonForcePrevious() [2/2]

const CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonForcePrevious ( void  ) const

Returns the previous velocity-increment container.

Returns
Borrowed const alias to a one-element integrator-owned container.

◆ getNoseHooverPistonMass() [1/2]

CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonMass ( void  )

Returns mutable scalar coupling-mass storage.

Returns
Borrowed mutable alias to the one-element container.
Warning
Preserve its one-element shape and host/device coherence.

◆ getNoseHooverPistonMass() [2/2]

const CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonMass ( void  ) const

Returns the scalar coupling-mass container.

Returns
Borrowed const alias to a one-element integrator-owned container. The accessor performs no transfer or synchronization.

◆ getNoseHooverPistonVelocity() [1/2]

CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonVelocity ( void  )

Returns mutable current extended-variable velocity storage.

Returns
Borrowed mutable alias to the one-element container.
Warning
Preserve its one-element shape and host/device coherence.

◆ getNoseHooverPistonVelocity() [2/2]

const CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonVelocity ( void  ) const

Returns the current extended-variable velocity container.

Returns
Borrowed const alias to a one-element integrator-owned container.

◆ getNoseHooverPistonVelocityPrevious() [1/2]

CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonVelocityPrevious ( void  )

Returns mutable previous extended-variable velocity storage.

Returns
Borrowed mutable alias to the one-element container.
Warning
Preserve its one-element shape and host/device coherence.

◆ getNoseHooverPistonVelocityPrevious() [2/2]

const CudaContainer< double > & CudaNoseHooverIntegrator::getNoseHooverPistonVelocityPrevious ( void  ) const

Returns the previous extended-variable velocity container.

Returns
Borrowed const alias to a one-element integrator-owned container.

◆ getReferenceTemperature()

double CudaNoseHooverIntegrator::getReferenceTemperature ( void  ) const

Returns the reference temperature.

Returns
The stored temperature in kelvin.

◆ initializeFromRestartFileImpl()

void CudaNoseHooverIntegrator::initializeFromRestartFileImpl ( const std::filesystem::path &  rstFilePath)
overrideprotectedvirtual

Restores Nose-Hoover state from a CHARMM-style restart file.

Parameters
[in]rstFilePathBorrowed restart-file path. The path is not canonicalized or retained.

Reimplemented from CudaIntegrator.

◆ removeCenterOfMassMotion()

void CudaNoseHooverIntegrator::removeCenterOfMassMotion ( void  )
protected

Removes mass-weighted center-of-mass displacement.

The method synchronizes the integrator stream, transfers velocity and previous-displacement storage to the host, applies the PBC-dependent correction, and transfers the displacement storage back to the device.

◆ resetAverageTemperature()

void CudaNoseHooverIntegrator::resetAverageTemperature ( void  )

Resets both running-temperature values and their sample count.

Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if the two-element temperature array cannot be reset on the device.
Postcondition
The sample count and both temperature averages are zero.

◆ setMaxPredictorCorrectorIterations()

void CudaNoseHooverIntegrator::setMaxPredictorCorrectorIterations ( const int  maxPredictorCorrectorIterations)

Sets the number of Nose-Hoover predictor-corrector iterations.

Parameters
[in]maxPredictorCorrectorIterationsPositive, dimensionless iteration count.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if maxPredictorCorrectorIterations is not positive.

◆ setNoseHooverPistonForce()

void CudaNoseHooverIntegrator::setNoseHooverPistonForce ( const double  noseHooverPistonForce)

Sets the current Nose-Hoover velocity-increment state.

Despite the public name, the propagation kernel stores a change in the extended-variable velocity rather than a physical force.

Parameters
[in]noseHooverPistonForceFinite native increment value. The repository does not establish its public dimensional convention.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if the value is non-finite.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if the scalar cannot be copied to device storage.

◆ setNoseHooverPistonForcePrevious()

void CudaNoseHooverIntegrator::setNoseHooverPistonForcePrevious ( const double  noseHooverPistonForcePrevious)

Sets the previous Nose-Hoover velocity-increment state.

Parameters
[in]noseHooverPistonForcePreviousFinite native previous-increment value. The repository does not establish its public dimensional convention.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if the value is non-finite.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if the scalar cannot be copied to device storage.

◆ setNoseHooverPistonMass()

void CudaNoseHooverIntegrator::setNoseHooverPistonMass ( const double  noseHooverPistonMass)

Sets the scalar Nose-Hoover coupling mass.

Parameters
[in]noseHooverPistonMassFinite non-negative native coupling-mass value. The repository does not establish its public dimensional convention.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if noseHooverPistonMass is non-finite or negative.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if the scalar cannot be copied to device storage.
Warning
Zero is currently accepted, but active propagation divides by the coupling mass.

◆ setNoseHooverPistonVelocity()

void CudaNoseHooverIntegrator::setNoseHooverPistonVelocity ( const double  noseHooverPistonVelocity)

Sets the current Nose-Hoover extended-variable velocity.

Parameters
[in]noseHooverPistonVelocityFinite native extended-state value. The repository does not establish its public dimensional convention.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if the value is non-finite.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if the scalar cannot be copied to device storage.

◆ setNoseHooverPistonVelocityPrevious()

void CudaNoseHooverIntegrator::setNoseHooverPistonVelocityPrevious ( const double  noseHooverPistonVelocityPrevious)

Sets the previous Nose-Hoover extended-variable velocity.

Parameters
[in]noseHooverPistonVelocityPreviousFinite native previous-state value. The repository does not establish its public dimensional convention.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if the value is non-finite.
ApoCharmmErrorWith code ApoCharmmErrorCode::Cuda if the scalar cannot be copied to device storage.

◆ setReferenceTemperature()

void CudaNoseHooverIntegrator::setReferenceTemperature ( const double  referenceTemperature)

Sets the Nose-Hoover reference temperature.

Parameters
[in]referenceTemperatureFinite non-negative temperature in kelvin.
Exceptions
ApoCharmmErrorWith code ApoCharmmErrorCode::InvalidArgument if referenceTemperature is non-finite or negative.

◆ useOldTemperature()

void CudaNoseHooverIntegrator::useOldTemperature ( const bool  usingOldTemperature)

Selects the on-step temperature estimator.

Parameters
[in]usingOldTemperaturetrue selects array element 1, the on-step “old” estimator, for native instantaneous temperature and thermostat feedback. false selects element 0, the three-point “new” estimator.

◆ usingOldTemperature()

bool CudaNoseHooverIntegrator::usingOldTemperature ( void  ) const

Returns the native temperature-estimator selector.

Returns
true when native feedback and instantaneous temperature use element 1; false when they use element 0.

Member Data Documentation

◆ m_AverageTemperature

CudaContainer<double> CudaNoseHooverIntegrator::m_AverageTemperature
protected

Stores two running-temperature estimators in kelvin.

The element order matches m_KineticEnergy.

◆ m_KineticEnergy

CudaContainer<double> CudaNoseHooverIntegrator::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_NoseHooverPistonForce

CudaContainer<double> CudaNoseHooverIntegrator::m_NoseHooverPistonForce
protected

Stores the current extended-variable velocity increment.

The propagation kernel treats this value as an increment despite the historical member name.