Provides shared lifecycle and scheduling for CUDA integrators. More...

#include <CudaIntegrator.h>

Inheritance diagram for CudaIntegrator:

Public Member Functions
	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
virtual void	initializeImpl (void)
	Initializes concrete state from the attached context.

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

virtual void	propagateOneStepImpl (void)
	Advances one concrete dynamics step.

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_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

Provides shared lifecycle and scheduling for CUDA integrators.

CudaIntegrator owns common trajectory counters, per-atom displacement storage, CUDA streams, optional holonomic-constraint state, subscriber scheduling, and a retained CharmmContext. Concrete integrators implement the protected initialization, restart, and one-step hooks.

The class is a polymorphic base but is not abstract. Direct calls to the base implementation's initialization, restart, descriptor, or one-step hooks throw ApoCharmmErrorCode::NotImplemented.

Context attachment and propagation are not thread-safe. Serialize all operations involving one integrator, its context, or its subscribers.

Warning: The current class does not declare copy or move operations. Treat native integrator objects as non-copyable because their resource-owning members do not have safe implicit-copy semantics.

See also: cuda_integrators

Constructor & Destructor Documentation

◆ CudaIntegrator() [1/3]

CudaIntegrator::CudaIntegrator ( void )

Constructs an unattached base integrator with no time step.

The constructor creates the primary integrator stream and a reserved memcpy stream. The initial public time step is zero, debug printing is disabled, the nonbonded-list interval is 20 steps, and the center-of-mass-removal interval is 1000 steps.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if either CUDA stream cannot be created.
std::bad_alloc	If allocation of a stream owner fails.

Postcondition: No context or subscriber is attached.

◆ CudaIntegrator() [2/3]

CudaIntegrator::CudaIntegrator ( const double timeStep )

Constructs an unattached integrator with a time step.

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 a CUDA stream cannot be created.
std::bad_alloc	If allocation of a stream owner fails.

Postcondition: The time step is stored internally in AKMA time.

◆ CudaIntegrator() [3/3]

CudaIntegrator::CudaIntegrator	(	const double	timeStep,
		const int	debugPrintFrequency
	)

Constructs an integrator with a time step and debug interval.

Parameters

[in]	timeStep	Finite positive time step in picoseconds.
[in]	debugPrintFrequency	Non-negative, dimensionless number of propagated steps between concrete-integrator debug calculations. Zero disables the feature.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `timeStep` is non-finite or not positive, or if `debugPrintFrequency` is negative.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if a CUDA stream cannot be created.
std::bad_alloc	If allocation of a stream owner fails.

◆ ~CudaIntegrator()

virtual CudaIntegrator::~CudaIntegrator ( void )

virtualnoexcept

Destroys the base integrator and its CUDA streams.

Destruction releases retained context, constraint, and subscriber owners only when the corresponding shared-pointer graph permits it. CUDA stream cleanup failures are discarded.

Member Function Documentation

◆ getCharmmContext() [1/2]

std::shared_ptr< CharmmContext > CudaIntegrator::getCharmmContext ( void )

Returns the retained context from a mutable integrator.

Returns: A copied shared owner of the context, or an empty std::shared_ptr before attachment. The returned owner can keep the context alive independently of this integrator.

◆ getCharmmContext() [2/2]

const std::shared_ptr< CharmmContext > CudaIntegrator::getCharmmContext ( void ) const

Returns the retained context from a const integrator.

Returns: A copied shared owner of the mutable context, or an empty std::shared_ptr before attachment. The returned owner can keep the context alive independently of this integrator.

◆ getCoordsDelta() [1/2]

CudaContainer< double4 > & CudaIntegrator::getCoordsDelta ( void )

Returns mutable current half-step displacement storage.

Returns: Borrowed mutable alias to the integrator-owned N-element CudaContainer<double4>.

Warning: Preserve the atom-count length and the concrete integrator's host/device state. Resizing or independently changing one mirror can invalidate later kernels.

◆ getCoordsDelta() [2/2]

const CudaContainer< double4 > & CudaIntegrator::getCoordsDelta ( void ) const

Returns the current half-step displacement container.

Returns: Borrowed const alias to the integrator-owned N-element CudaContainer<double4>, where N is the attached context atom count. Components x, y, and z contain angstrom-valued displacements. The integrator assigns no public meaning to w.

Note: The accessor performs no host/device transfer or synchronization. The alias remains valid until integrator destruction or structural mutation of the container.

◆ getCoordsDeltaPrevious() [1/2]

CudaContainer< double4 > & CudaIntegrator::getCoordsDeltaPrevious ( void )

Returns mutable previous half-step displacement storage.

Returns: Borrowed mutable alias to the integrator-owned N-element CudaContainer<double4>.

Warning: Preserve the atom-count length, component interpretation, and host/device coherence expected by the concrete integrator.

◆ getCoordsDeltaPrevious() [2/2]

const CudaContainer< double4 > & CudaIntegrator::getCoordsDeltaPrevious ( void ) const

Returns the previous half-step displacement container.

Returns: Borrowed const alias to the integrator-owned N-element CudaContainer<double4>. Components x, y, and z contain angstrom-valued displacements; w has no public integrator meaning.

Note: The accessor performs no host/device transfer or synchronization.

◆ getCurrentPropagatedStep()

int CudaIntegrator::getCurrentPropagatedStep ( void ) const

Returns the wrapped completed-step counter.

Returns: A dimensionless value in the range zero through INT_MAX.

Note: propagate() increments this counter after each successful concrete step and wraps INT_MAX + 1 to zero. Direct propagateOneStep() calls do not increment it.

◆ getIntegratorDescriptors()

virtual std::map< std::string, std::string > CudaIntegrator::getIntegratorDescriptors ( void )

virtual

Returns key/value descriptors for the concrete integrator.

Returns: A newly allocated map whose strings describe the concrete integrator.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotImplemented` when the base implementation is called.
std::bad_alloc	If a concrete implementation cannot allocate the result.

◆ getNumSteps()

int CudaIntegrator::getNumSteps ( void ) const

Returns the most recently requested propagation length.

Returns: The positive dimensionless numSteps value from the most recent accepted propagate() call, or zero before the first call.

◆ getReportFreqList() [1/2]

std::vector< int > & CudaIntegrator::getReportFreqList ( void )

Returns mutable access to cached subscriber frequencies.

Returns: Borrowed mutable alias to the integrator-owned vector.

Warning: Every value must remain positive and the vector must remain the same length and order as m_Subscribers. Mutation bypasses validation.

◆ getReportFreqList() [2/2]

const std::vector< int > & CudaIntegrator::getReportFreqList ( void ) const

Returns the cached subscriber-frequency array.

Returns: Borrowed const alias to positive, dimensionless intervals. Entry i schedules subscriber entry i. The alias remains valid until vector reallocation, integrator destruction, or non-const mutation.

◆ getSubscribers() [1/2]

std::vector< std::shared_ptr< Subscriber > > & CudaIntegrator::getSubscribers ( void )

Returns mutable access to the attached subscriber array.

Returns: Borrowed mutable alias to the integrator-owned vector.

Warning: The vector must remain the same length and order as m_ReportFreqList. Direct mutation can violate that invariant and cause out-of-bounds access or callbacks to the wrong subscriber.

◆ getSubscribers() [2/2]

const std::vector< std::shared_ptr< Subscriber > > & CudaIntegrator::getSubscribers ( void ) const

Returns the attached subscriber array.

Returns: Borrowed const alias to the integrator-owned vector. Each element is a shared owner of a subscriber. The alias remains valid until vector reallocation, integrator destruction, or non-const mutation.

◆ getTimeStep()

double CudaIntegrator::getTimeStep ( void ) const

Returns the public integrator time step.

Returns: The configured time step in picoseconds, or zero for a default-constructed base object whose time step has not been set.

◆ getTotNumSteps()

unsigned long long int CudaIntegrator::getTotNumSteps ( void ) const

Returns the total number of requested propagation steps.

Returns: The dimensionless sum of every accepted propagate() request.

Warning: A request is added before its first concrete step. After a propagation failure this value can exceed the number of completed steps.

◆ initialize()

virtual void CudaIntegrator::initialize ( void )

finalvirtual

Reinitializes concrete integrator state from the attached context.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if no context is attached or a concrete initialization prerequisite is absent.
ApoCharmmError	With code `ApoCharmmErrorCode::NotImplemented` if the direct base hook is reached.
ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument`, `ApoCharmmErrorCode::Runtime`, or `ApoCharmmErrorCode::Cuda` when reported by the concrete initialization hook.
std::bad_alloc	If host work storage cannot be allocated.

Postcondition: On success, concrete displacement, kinetic, constraint, and RNG state has been regenerated from the current context and configuration.

Warning: Reinitialization can overwrite state restored from a restart file or accumulated during earlier propagation.

◆ initializeFromRestartFile()

virtual void CudaIntegrator::initializeFromRestartFile ( const std::filesystem::path & rstFilePath )

finalvirtual

Initializes concrete integrator state from a restart file.

Parameters

[in] rstFilePath Borrowed file-system path used only for this call. The path is not canonicalized or retained.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if no context is attached or required concrete state is missing.
ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if restart state is incompatible with the configured context or piston layout.
ApoCharmmError	With code `ApoCharmmErrorCode::NotImplemented` if the direct base hook is reached.
ApoCharmmError	With code `ApoCharmmErrorCode::Runtime` if the file cannot be opened, parsed, or interpreted.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if restored state cannot be transferred or synchronized.
std::bad_alloc	If parsing or state allocation fails.

Warning: Restart loading is not transactional. State parsed or transferred before a later failure can remain observable.

◆ initializeFromRestartFileImpl()

virtual void CudaIntegrator::initializeFromRestartFileImpl ( const std::filesystem::path & rstFilePath )

protectedvirtual

Initializes concrete state from a restart file.

Parameters

[in] rstFilePath Borrowed restart-file path.

Precondition: m_Context is non-null.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::NotImplemented in the base implementation.

Reimplemented in CudaLangevinPistonIntegrator, CudaLangevinThermostatIntegrator, and CudaNoseHooverIntegrator.

◆ initializeImpl()

virtual void CudaIntegrator::initializeImpl ( void )

protectedvirtual

Initializes concrete state from the attached context.

Derived implementations may allocate work arrays, initialize RNG state, calculate forces, and synchronize the primary integrator stream.

Precondition: m_Context is non-null.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::NotImplemented in the base implementation.

Reimplemented in CudaLangevinPistonIntegrator, CudaLangevinThermostatIntegrator, and CudaNoseHooverIntegrator.

◆ propagate()

void CudaIntegrator::propagate ( const int numSteps )

Propagates dynamics and invokes scheduled subscriber updates.

The method validates readiness, resets the context neighbor list, resets the per-call neighbor-list counter, stores numSteps, and adds the full request to the total-step counter before entering the loop. Local loop indices run from one through numSteps.

After each successful concrete step, the method increments the neighbor-list counter and wrapped current-step counter, performs a periodic NaN-energy check, and synchronously invokes subscribers whose cached reporting interval divides the local loop index. A later call restarts the local subscriber schedule at one.

Parameters

[in] numSteps Positive number of dynamics steps to request.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `numSteps` is not positive or a native participant rejects an argument.
ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if the context, force manager, concrete integrator, or scheduled subscriber lacks required state.
ApoCharmmError	With code `ApoCharmmErrorCode::NotImplemented` if a concrete operation or subscriber reports an unsupported operation.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if force evaluation, a kernel, a transfer, or CUDA synchronization fails.
ApoCharmmError	With code `ApoCharmmErrorCode::Runtime` if a runtime readiness check, NaN check, subscriber file operation, or other native runtime operation fails.
std::invalid_argument	If a scheduled legacy `DynaSubscriber` rejects its current integrator.
std::runtime_error	If a scheduled legacy `XYZSubscriber` has no attached context.

Precondition: An attached context must expose a non-null initialized force manager.

Postcondition: On success, exactly numSteps concrete steps and all matching callbacks have completed.; The total-step counter has increased by numSteps, and the most-recent-request counter equals numSteps.

Warning: The operation is not transactional. The total-step counter records requested steps and is incremented before the first concrete step. Earlier steps, state changes, and output bytes remain observable after a later failure.

◆ propagateOneStep()

virtual void CudaIntegrator::propagateOneStep ( void )

finalvirtual

Propagates one concrete dynamics step without base-loop bookkeeping.

This entry point checks context and force-manager readiness and invokes the concrete one-step hook. It does not reset the neighbor list, increment public step counters, run scheduled subscribers, or perform the base periodic NaN check.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if context or force-manager state is not ready.
ApoCharmmError	With code `ApoCharmmErrorCode::NotImplemented` if the direct base hook is reached.
ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument`, `ApoCharmmErrorCode::Runtime`, or `ApoCharmmErrorCode::Cuda` when reported by the concrete step.

Postcondition: On success, one concrete step has changed context and integrator state, but the base trajectory counters are unchanged.

◆ propagateOneStepImpl()

virtual void CudaIntegrator::propagateOneStepImpl ( void )

protectedvirtual

Advances one concrete dynamics step.

Derived implementations update context coordinates, velocities, forces, and their own state. They do not update the base public step counters or subscriber schedule.

Precondition: requirePropagationReady() has succeeded.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::NotImplemented in the base implementation.

Reimplemented in CudaLangevinPistonIntegrator, CudaLangevinThermostatIntegrator, and CudaNoseHooverIntegrator.

◆ reportIfNeeded()

void CudaIntegrator::reportIfNeeded ( const int istep )

protected

Invokes subscribers scheduled for one local propagation step.

The method iterates over the cached frequency array and calls m_Subscribers[i]->update() when istep % m_ReportFreqList[i] == 0. Calls are synchronous and occur in subscriber-vector order.

Parameters

[in] istep Positive step index local to the current propagation call.

Precondition: m_Subscribers and m_ReportFreqList have identical lengths and corresponding order, and every cached frequency is positive.

Note: Any exception raised by a subscriber propagates immediately. Later subscribers scheduled for the same step are not called.

◆ requirePropagationReady()

void CudaIntegrator::requirePropagationReady ( void ) const

protected

Validates shared state required for propagation.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::NotInitialized if the context is absent, its force manager is absent, or the force manager is not initialized.

◆ setCharmmContext()

virtual void CudaIntegrator::setCharmmContext ( std::shared_ptr< CharmmContext > ctx )

finalvirtual

Attaches a context and initializes concrete integrator state.

The method retains ctx, resizes the three base per-atom work containers, snapshots the context's holonomic-constraint setting, constructs and sets up the constraint helper when required, and invokes the concrete initializeImpl() hook.

Parameters

[in] ctx Non-null shared context owner. The shared owner is copied and retained on success.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `ctx` is null or a context has already been attached.
ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if the context atom count is not initialized or a concrete integrator lacks required state such as a piston crystal type.
ApoCharmmError	With code `ApoCharmmErrorCode::NotImplemented` if the direct base initialization hook is reached.
ApoCharmmError	With code `ApoCharmmErrorCode::Cuda` if allocation, setup, transfer, kernel launch, or synchronization fails.
ApoCharmmError	With code `ApoCharmmErrorCode::Runtime` for a concrete runtime initialization failure.
std::bad_alloc	If host or shared-owner allocation fails.

Precondition: Configure the time step and all concrete initialization prerequisites before this call. In particular, a Langevin-piston integrator requires a supported crystal type.

Postcondition: On success, the context is retained and concrete device state is initialized.; On failure, the retained context and constraint helper are cleared. Per-atom base containers resized before the failure may remain resized.

Warning: A second attachment is not supported, even when the argument is the same context.

◆ setDebugPrintFrequency()

void CudaIntegrator::setDebugPrintFrequency ( const int freq )

Sets the concrete-integrator debug-calculation interval.

Parameters

[in] freq Non-negative, dimensionless number of propagated steps between debug calculations. Zero disables the feature.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if freq is negative.

Note: The base class stores this value. Whether and what a concrete integrator calculates at the interval is implementation-specific.

◆ setNonbondedListUpdateFrequency()

void CudaIntegrator::setNonbondedListUpdateFrequency ( const int freq )

Sets the nonbonded neighbor-list update interval.

Parameters

[in] freq Positive, dimensionless number of propagated steps between concrete-integrator neighbor-list resets.

Exceptions

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

Note: The per-call counter is reset to zero before propagate() enters its loop, so concrete implementations test the update condition during the first requested step.

◆ setRemoveCenterOfMassFrequency()

void CudaIntegrator::setRemoveCenterOfMassFrequency ( const int freq )

Sets the center-of-mass-removal interval.

Parameters

[in] freq Positive, dimensionless number of propagated steps between concrete-integrator center-of-mass corrections.

Exceptions

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

Note: The wrapped current-step counter starts at zero, so the concrete integrators perform their correction during the first propagated step.

◆ setTimeStep()

void CudaIntegrator::setTimeStep ( const double dt )

Sets the public integrator time step.

Parameters

[in] dt Finite positive time step in picoseconds.

Exceptions

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

Postcondition: The internal scalar contains dt / 0.0488882129 AKMA time.

Warning: This method does not rebuild an attached holonomic-constraint helper or reinitialize concrete-integrator coefficients and displacement history. Configure the time step before attaching a context.

◆ subscribe() [1/2]

void CudaIntegrator::subscribe ( const std::vector< std::shared_ptr< Subscriber > > & sublist )

Attaches subscribers sequentially in vector order.

Parameters

[in] sublist Borrowed vector of shared subscriber owners. Each element is passed to the single-subscriber overload and retained on success.

Note: Exceptions from the single-subscriber overload propagate unchanged, including ApoCharmmError and std::bad_alloc.

Postcondition: On success, every element has been attached in input order.

Warning: The operation is not transactional. Subscribers attached before a failing element remain attached.

◆ subscribe() [2/2]

void CudaIntegrator::subscribe ( std::shared_ptr< Subscriber > sub )

Attaches one subscriber and caches its reporting interval.

The method rejects null and duplicate subscribers, obtains a shared owner of this integrator, calls sub->setCharmmContext(m_Context), calls sub->setIntegrator(...), appends the subscriber, and appends its current report frequency to the parallel scheduling array.

Parameters

[in] sub Non-null shared subscriber owner retained on success.

Exceptions

ApoCharmmError	With code `ApoCharmmErrorCode::InvalidArgument` if `sub` is null, is already present, or rejects a second context or integrator attachment.
ApoCharmmError	With code `ApoCharmmErrorCode::NotInitialized` if this integrator is not owned by a `std::shared_ptr` and therefore cannot obtain a shared self-reference.
std::bad_alloc	If appending either scheduling array cannot allocate.

Precondition: Call setCharmmContext with a non-null context before attaching a subscriber that requires context state.

Postcondition: On success, the integrator and subscriber retain each other, the subscriber retains the current context, and the current frequency is cached.

Warning: Attachment is not transactional. Failure after a backlink or first vector append can leave partial state.

◆ unsubscribe() [1/2]

void CudaIntegrator::unsubscribe ( const std::vector< std::shared_ptr< Subscriber > > & sublist )

Removes subscribers sequentially in vector order.

Parameters

[in] sublist Borrowed vector of subscriber identities. Each element is passed to the single-subscriber overload.

Note: Exceptions from the single-subscriber overload propagate unchanged.

Postcondition: On success, every listed subscriber has been removed.

Warning: The operation is not transactional. Subscribers removed before a failing element remain removed.

◆ unsubscribe() [2/2]

void CudaIntegrator::unsubscribe ( std::shared_ptr< Subscriber > sub )

Removes one subscriber and its cached reporting interval.

Parameters

[in] sub Non-null shared subscriber identity to remove. The argument is borrowed for lookup; removing it releases only the integrator's owner.

Exceptions

ApoCharmmError With code ApoCharmmErrorCode::InvalidArgument if sub is null or is not present.

Postcondition: On success, the corresponding entries are erased from both parallel arrays.

Warning: The removed subscriber still retains its context and integrator. Those backlinks are not cleared, and normal resubscription of the same object therefore fails.

Member Data Documentation

◆ m_Context

std::shared_ptr<CharmmContext> CudaIntegrator::m_Context

protected

Retains the context attached to this integrator.

The owner is empty before attachment and is cleared when attachment initialization fails.

◆ m_CoordsDelta

CudaContainer<double4> CudaIntegrator::m_CoordsDelta

protected

Stores current half-step displacements.

The container has one double4 record per context atom. Concrete kernels use the x, y, and z components in angstroms.

◆ m_CoordsDeltaPrevious

CudaContainer<double4> CudaIntegrator::m_CoordsDeltaPrevious

protected

Stores previous half-step displacements.

The container has one double4 record per context atom. Concrete kernels use the x, y, and z components in angstroms.

◆ m_CoordsRef

CudaContainer<double4> CudaIntegrator::m_CoordsRef

protected

Stores per-atom reference coordinates used by concrete steps.

The container has one double4 record per context atom. Concrete kernels use the x, y, and z components in angstroms.

◆ m_CurrentPropagatedStep

int CudaIntegrator::m_CurrentPropagatedStep

protected

Stores the wrapped number of completed base-loop steps.

The value wraps to zero after INT_MAX and is not changed by direct propagateOneStep() calls.

◆ m_DebugPrintFrequency

int CudaIntegrator::m_DebugPrintFrequency

protected

Stores the non-negative concrete debug-calculation interval.

Zero disables the feature.

◆ m_HolonomicConstraint

std::shared_ptr<CudaHolonomicConstraint> CudaIntegrator::m_HolonomicConstraint

protected

Retains the optional holonomic-constraint helper.

The helper is created during context attachment when the context reports that holonomic constraints are enabled.

◆ m_IntegratorMemcpyStream

std::shared_ptr<cudaStream_t> CudaIntegrator::m_IntegratorMemcpyStream

protected

Owns a reserved CUDA memcpy stream.

The currently documented concrete integrators allocate this stream but do not issue their inspected transfer paths on it.

◆ m_IntegratorStream

std::shared_ptr<cudaStream_t> CudaIntegrator::m_IntegratorStream

protected

Owns the primary CUDA stream used by concrete integrator work.

Concrete initialization and complete-step paths synchronize this stream at their explicit completion boundaries.

◆ m_IntegratorTypeName

std::string CudaIntegrator::m_IntegratorTypeName

protected

Stores the concrete integrator label used by subscribers.

Restart and descriptor code uses this string to discriminate supported integrator state layouts.

◆ m_ReportFreqList

std::vector<int> CudaIntegrator::m_ReportFreqList

protected

Stores the frequency snapshot for each attached subscriber.

Entry i is the positive, dimensionless reporting interval copied from subscriber i during attachment. Later changes to the subscriber property do not update this array.

◆ m_StepsSinceNeighborListUpdate

int CudaIntegrator::m_StepsSinceNeighborListUpdate

protected

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

propagate() resets this value to zero before the loop and increments it after each successful concrete step.

◆ m_Subscribers

std::vector<std::shared_ptr<Subscriber> > CudaIntegrator::m_Subscribers

protected

Retains subscribers in callback order.

Entry i must correspond to entry i in m_ReportFreqList. Each shared pointer owns the subscriber until successful unsubscription or integrator destruction.

◆ m_TimeStep

double CudaIntegrator::m_TimeStep

protected

Stores the internal time step in AKMA time.

Public setters divide picoseconds by m_Timfac before storing this value.

◆ m_Timfac

double CudaIntegrator::m_Timfac

protected

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

The current value is 0.0488882129, with AKMA time = picoseconds / m_Timfac.

◆ m_TotNumSteps

unsigned long long int CudaIntegrator::m_TotNumSteps

protected

Stores the accumulated number of requested propagation steps.

Each accepted request is added before any step in that request executes.

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CudaIntegrator() [1/3]

◆ CudaIntegrator() [2/3]

◆ CudaIntegrator() [3/3]

◆ ~CudaIntegrator()

Member Function Documentation

◆ getCharmmContext() [1/2]

◆ getCharmmContext() [2/2]

◆ getCoordsDelta() [1/2]

◆ getCoordsDelta() [2/2]

◆ getCoordsDeltaPrevious() [1/2]

◆ getCoordsDeltaPrevious() [2/2]

◆ getCurrentPropagatedStep()

◆ getIntegratorDescriptors()

◆ getNumSteps()

◆ getReportFreqList() [1/2]

◆ getReportFreqList() [2/2]

◆ getSubscribers() [1/2]

◆ getSubscribers() [2/2]

◆ getTimeStep()

◆ getTotNumSteps()

◆ initialize()

◆ initializeFromRestartFile()

◆ initializeFromRestartFileImpl()

◆ initializeImpl()

◆ propagate()

◆ propagateOneStep()

◆ propagateOneStepImpl()

◆ reportIfNeeded()

◆ requirePropagationReady()

◆ setCharmmContext()

◆ setDebugPrintFrequency()

◆ setNonbondedListUpdateFrequency()

◆ setRemoveCenterOfMassFrequency()

◆ setTimeStep()

◆ subscribe() [1/2]

◆ subscribe() [2/2]

◆ unsubscribe() [1/2]

◆ unsubscribe() [2/2]

Member Data Documentation

◆ m_Context

◆ m_CoordsDelta

◆ m_CoordsDeltaPrevious

◆ m_CoordsRef

◆ m_CurrentPropagatedStep

◆ m_DebugPrintFrequency

◆ m_HolonomicConstraint

◆ m_IntegratorMemcpyStream

◆ m_IntegratorStream

◆ m_IntegratorTypeName

◆ m_ReportFreqList

◆ m_StepsSinceNeighborListUpdate

◆ m_Subscribers

◆ m_TimeStep

◆ m_Timfac

◆ m_TotNumSteps