AtomReference Class Reference

Retains one zero-based atom index and shared ownership of its topology. More...

#include <AtomReference.h>

Public Member Functions
	AtomReference (void)=delete
	Prevents construction without a topology and atom index.
	AtomReference (std::shared_ptr< const CharmmPSF > psf, const int atomIndex)
	Constructs a reference to one atom in a native PSF.
	AtomReference (const AtomReference &other) noexcept=default
	Constructs a reference with the same topology and atom index.
	AtomReference (AtomReference &&other) noexcept=default
	Constructs a reference by moving another reference.
AtomReference &	operator= (const AtomReference &other) noexcept=default
	Replaces this value with a copy of another reference.
AtomReference &	operator= (AtomReference &&other) noexcept=default
	Replaces this value by moving another reference.
int	getAtomIndex (void) const noexcept
	Returns the referenced atom index.
std::shared_ptr< const CharmmPSF >	getPsf (void) const noexcept
	Returns shared ownership of the originating topology.
bool	hasSameTopology (const AtomReference &other) const noexcept
	Tests whether another reference originates from the same topology.
bool	operator== (const AtomReference &other) const noexcept
	Tests topology-aware atom-reference equality.
bool	operator!= (const AtomReference &other) const noexcept
	Tests topology-aware atom-reference inequality.

Detailed Description

Retains one zero-based atom index and shared ownership of its topology.

AtomReference stores a valid atom index together with a std::shared_ptr<const CharmmPSF> for the native topology that defines that index. It does not retain an AtomSelection, allocate per-atom storage, store coordinates, or perform CUDA work.

Topology identity is native object identity. Two references have the same topology only when their shared pointers address the same CharmmPSF object. Equality additionally requires the same atom index.

The object exposes no setters. Copy operations share ownership of the same topology, while move operations transfer the stored shared pointer. Whole-object copy and move assignment remain available. A moved-from object remains valid for destruction or assignment, but its query results are unspecified.

The class provides no internal locking. Concurrent read-only queries are valid only while no thread assigns to or destroys either reference and no thread mutates the shared topology through another owner.

See also

AtomSelector::selectAtom

Constructor & Destructor Documentation

AtomReference() [1/3]

AtomReference::AtomReference	(	std::shared_ptr< const CharmmPSF >	psf,
		const int	atomIndex
	)

Constructs a reference to one atom in a native PSF.

Validation is performed in this order: the PSF pointer must be non-null, its atom count must be initialized and non-negative, and atomIndex must be in [0, psf->getNumAtoms()).

Parameters

[in]	psf	Shared pointer to the originating topology. The pointer is retained without cloning the PSF.
[in]	atomIndex	Zero-based, dimensionless atom index.

Exceptions

ApoCharmmError	With ApoCharmmErrorCode::InvalidArgument if psf is null.
ApoCharmmError	With ApoCharmmErrorCode::NotInitialized if the PSF atom count is negative.
ApoCharmmError	With ApoCharmmErrorCode::InvalidArgument if atomIndex is outside [0, psf->getNumAtoms()).
std::bad_alloc	If diagnostic allocation fails.
std::length_error	If a diagnostic exceeds an implementation-defined limit.

Postcondition

The new object retains shared ownership of the supplied native PSF.

getAtomIndex() == atomIndex.

AtomReference() [2/3]

AtomReference::AtomReference ( const AtomReference &  other )

defaultnoexcept

Constructs a reference with the same topology and atom index.

Parameters

[in]

other

Reference to copy. The source remains unchanged.

Postcondition

The new object compares equal to other and shares topology ownership with it.

AtomReference() [3/3]

AtomReference::AtomReference ( AtomReference &&  other )

defaultnoexcept

Constructs a reference by moving another reference.

Parameters

[in,out]

other

Reference whose stored shared pointer is transferred.

Postcondition

The new object has the topology and atom index held by other before the move. The moved-from object remains valid for destruction or assignment.

Member Function Documentation

getAtomIndex()

int AtomReference::getAtomIndex ( void  ) const

noexcept

Returns the referenced atom index.

Returns

The zero-based, dimensionless atom index supplied at construction or assignment.

getPsf()

std::shared_ptr< const CharmmPSF > AtomReference::getPsf ( void  ) const

noexcept

Returns shared ownership of the originating topology.

Returns

A copied std::shared_ptr<const CharmmPSF> addressing the same native PSF object retained by this reference.

hasSameTopology()

bool AtomReference::hasSameTopology ( const AtomReference &  other ) const

noexcept

Tests whether another reference originates from the same topology.

Parameters

[in]

other

Reference whose native PSF object identity is compared.

Returns

true only when both shared pointers address the same native CharmmPSF object; otherwise false.

operator!=()

bool AtomReference::operator!= ( const AtomReference &  other ) const

noexcept

Tests topology-aware atom-reference inequality.

Parameters

[in]

other

Reference to compare.

Returns

true when the references differ in native PSF object identity, atom index, or both; otherwise false.

operator=() [1/2]

AtomReference & AtomReference::operator= ( AtomReference &&  other )

defaultnoexcept

Replaces this value by moving another reference.

Parameters

[in,out]

other

Reference whose stored shared pointer is transferred.

Returns

A borrowed mutable reference to this object.

Postcondition

This object has the topology and atom index held by other before the move. The moved-from object remains valid for destruction or assignment.

operator=() [2/2]

AtomReference & AtomReference::operator= ( const AtomReference &  other )

defaultnoexcept

Replaces this value with a copy of another reference.

Parameters

[in]

other

Reference to copy. The source remains unchanged.

Returns

A borrowed mutable reference to this object.

Postcondition

This object compares equal to other and shares topology ownership with it.

operator==()

bool AtomReference::operator== ( const AtomReference &  other ) const

noexcept

Tests topology-aware atom-reference equality.

Parameters

[in]

other

Reference to compare.

Returns

true only when both references have the same native PSF object identity and the same atom index; otherwise false.