Owns a compact host-resident set of zero-based atom indices. More...

#include <AtomSelection.h>

Public Types
enum class	InitialValue { NONE , ALL }
	Selects the value assigned to every atom during initialization. More...

Public Member Functions
	AtomSelection (void)=delete
	Prevents construction without an explicit atom count.

	AtomSelection (const int numAtoms, const InitialValue initialValue=InitialValue::NONE)
	Constructs a selection for a fixed number of atoms.

	AtomSelection (const AtomSelection &other)
	Constructs an independent copy of another selection.

	AtomSelection (const AtomSelection &&other)
	Constructs an independent copy from a const rvalue.

AtomSelection &	operator= (const AtomSelection &other)
	Replaces this selection with an independent copy.

AtomSelection &	operator= (const AtomSelection &&other)
	Replaces this selection with a copy of a const rvalue.

AtomSelection &	operator&= (const AtomSelection &other)
	Intersects this selection with another selection.

AtomSelection &	operator\|= (const AtomSelection &other)
	Unites this selection with another selection.

int	getNumAtoms (void) const
	Returns the represented atom count.

int	getNumSelected (void) const
	Returns the number of selected atoms.

std::vector< int >	getAtomIndices (void) const
	Returns all selected atom indices in ascending order.

void	setNumAtoms (const int numAtoms, const InitialValue initialValue=InitialValue::NONE)
	Resets the selection for a new atom count.

bool	contains (const int atomIndex) const
	Tests whether one atom index is selected.

void	set (const int atomIndex, const bool isSelected=true)
	Sets or clears one atom-selection bit.

void	clear (void)
	Clears every atom-selection bit.

void	fill (void)
	Selects every represented atom.

Detailed Description

Owns a compact host-resident set of zero-based atom indices.

AtomSelection associates one selection bit with every atom in the range [0, getNumAtoms()). Internally, consecutive groups of 64 atoms occupy one std::uint64_t; atom i uses word i / 64 and the bit at offset i % 64. Unused high bits in the final word are always cleared. Counts and indices are dimensionless.

The object exclusively owns its host storage. Copy construction and the copy-like const AtomSelection && overload create independent storage. Logical operations require both operands to describe the same atom count. Resizing resets the complete selection rather than preserving an overlap.

This class performs no CUDA allocation, transfer, stream operation, or synchronization. The compiler-generated destructor only releases host storage. The class provides no internal locking: concurrent read-only calls are valid only while no thread mutates or destroys the object.

Note: The normal representation invariant is m_Words.size() == ceil(getNumAtoms() / 64) with all out-of-range bits zero.

Warning: Copy assignment is sequential rather than transactional. If vector assignment fails after the atom count changes, the destination can violate its representation invariant.

See also: atom_selection

Member Enumeration Documentation

◆ InitialValue

enum class AtomSelection::InitialValue

strong

Selects the value assigned to every atom during initialization.

Enumerator
NONE	Leaves every valid atom index unselected.
ALL	Selects every valid atom index.

Constructor & Destructor Documentation

◆ AtomSelection() [1/3]

AtomSelection::AtomSelection	(	const int	numAtoms,
		const InitialValue	initialValue = `InitialValue::NONE`
	)

Constructs a selection for a fixed number of atoms.

The object allocates enough host words to represent numAtoms bits and initializes every valid bit according to initialValue.

Parameters

[in]	numAtoms	Dimensionless atom count. The value must be non-negative.
[in]	initialValue	Initial selection state applied to every atom.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `numAtoms` is negative.
std::bad_alloc	If bit-storage or diagnostic allocation fails.
std::length_error	If the requested storage or diagnostic exceeds an implementation-defined limit.

Postcondition: getNumAtoms() == numAtoms.; getNumSelected() is zero for InitialValue::NONE and numAtoms for InitialValue::ALL.

◆ AtomSelection() [2/3]

AtomSelection::AtomSelection ( const AtomSelection & other )

Constructs an independent copy of another selection.

Parameters

[in] other Selection borrowed for the duration of construction. No reference to it is retained.

Exceptions

std::bad_alloc	If the owned word vector cannot be copied.
std::length_error	If the copied storage exceeds an implementation-defined limit.

Postcondition: The new object has the same atom count and selected indices as other, without aliasing its storage.

◆ AtomSelection() [3/3]

AtomSelection::AtomSelection ( const AtomSelection && other )

Constructs an independent copy from a const rvalue.

Parameters

[in] other Const selection rvalue borrowed during construction. The source remains unchanged and is not retained.

Exceptions

std::bad_alloc	If the owned word vector cannot be copied.
std::length_error	If the copied storage exceeds an implementation-defined limit.

Postcondition: The new object has the same atom count and selected indices as other, without aliasing its storage.

Warning: Because other is const, this overload copies and is not an ownership-transferring move constructor.

Member Function Documentation

◆ clear()

void AtomSelection::clear ( void )

Clears every atom-selection bit.

Postcondition: getNumSelected() == 0 and the atom count is unchanged.

◆ contains()

bool AtomSelection::contains ( const int atomIndex ) const

Tests whether one atom index is selected.

Parameters

[in] atomIndex Zero-based, dimensionless atom index. The value must be in [0, getNumAtoms()).

Returns: true when the corresponding bit is set; otherwise false.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `atomIndex` is outside the represented range.
std::bad_alloc	If range-error diagnostic allocation fails.
std::length_error	If a range-error diagnostic exceeds an implementation-defined limit.

◆ fill()

void AtomSelection::fill ( void )

Selects every represented atom.

Postcondition: getNumSelected() == getNumAtoms() and unused final-word bits remain zero.

◆ getAtomIndices()

std::vector< int > AtomSelection::getAtomIndices ( void ) const

Returns all selected atom indices in ascending order.

Returns: A newly owned host vector of zero-based indices. Its length equals getNumSelected(), and it does not alias this object.

Exceptions

std::bad_alloc	If the result vector cannot allocate storage.
std::length_error	If the result exceeds an implementation-defined vector limit.

◆ getNumAtoms()

int AtomSelection::getNumAtoms ( void ) const

Returns the represented atom count.

Returns: The non-negative, dimensionless count established at construction or by setNumAtoms().

◆ getNumSelected()

int AtomSelection::getNumSelected ( void ) const

Returns the number of selected atoms.

Returns: A dimensionless value in [0, getNumAtoms()] computed from the stored bits.

◆ operator&=()

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

Intersects this selection with another selection.

Parameters

[in] other Selection whose bits are combined with this object. The operand is borrowed and remains unchanged.

Returns: A borrowed mutable reference to this object.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if the atom counts differ.
std::bad_alloc	If mismatch-diagnostic allocation fails.
std::length_error	If a mismatch diagnostic exceeds an implementation-defined limit.

Postcondition: On success, an atom is selected exactly when it was selected in both operands.; If the atom counts differ, this object is unchanged.

◆ operator=() [1/2]

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

Replaces this selection with a copy of a const rvalue.

Parameters

[in] other Const selection rvalue borrowed during assignment. The source remains unchanged and is not retained.

Returns: A borrowed mutable reference to this object.

Exceptions

std::bad_alloc	If the owned word vector cannot be copied.
std::length_error	If the copied storage exceeds an implementation-defined limit.

Postcondition: On success, this object has the same atom count and selected indices as other without aliasing its storage.

Warning: Because other is const, this overload copies and does not transfer ownership.; The atom count is assigned before the word vector. A failed vector assignment can leave this object with a new count and old word storage.

◆ operator=() [2/2]

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

Replaces this selection with an independent copy.

Parameters

[in] other Selection borrowed for the duration of assignment. No reference to it is retained.

Returns: A borrowed mutable reference to this object.

Exceptions

std::bad_alloc	If the owned word vector cannot be copied.
std::length_error	If the copied storage exceeds an implementation-defined limit.

Postcondition: On success, this object has the same atom count and selected indices as other without aliasing its storage.

Warning: The atom count is assigned before the word vector. A failed vector assignment can leave this object with a new count and old word storage.

◆ operator|=()

AtomSelection & AtomSelection::operator|= ( const AtomSelection & other )

Unites this selection with another selection.

Parameters

[in] other Selection whose bits are combined with this object. The operand is borrowed and remains unchanged.

Returns: A borrowed mutable reference to this object.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if the atom counts differ.
std::bad_alloc	If mismatch-diagnostic allocation fails.
std::length_error	If a mismatch diagnostic exceeds an implementation-defined limit.

Postcondition: On success, an atom is selected when it was selected in either operand.; If the atom counts differ, this object is unchanged.

◆ set()

void AtomSelection::set	(	const int	atomIndex,
		const bool	isSelected = `true`
	)

Sets or clears one atom-selection bit.

Parameters

[in]	atomIndex	Zero-based, dimensionless atom index. The value must be in `[0, getNumAtoms())`.
[in]	isSelected	`true` to select the atom or `false` to clear it.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `atomIndex` is outside the represented range.
std::bad_alloc	If range-error diagnostic allocation fails.
std::length_error	If a range-error diagnostic exceeds an implementation-defined limit.

Postcondition: On success, contains(atomIndex) == isSelected and all other bits are unchanged.; If atomIndex is invalid, the selection is unchanged.

◆ setNumAtoms()

void AtomSelection::setNumAtoms	(	const int	numAtoms,
		const InitialValue	initialValue = `InitialValue::NONE`
	)

Resets the selection for a new atom count.

This operation replaces all existing bits. It does not preserve selected atoms from the old range.

Parameters

[in]	numAtoms	New dimensionless atom count. The value must be non-negative.
[in]	initialValue	State assigned to every atom in the new range.

Exceptions

ApoCharmmError	With `ApoCharmmErrorCode::InvalidArgument` if `numAtoms` is negative.
std::bad_alloc	If replacement storage or diagnostic allocation fails.
std::length_error	If replacement storage or a diagnostic exceeds an implementation-defined limit.

Postcondition: On success, getNumAtoms() == numAtoms and the selected count is either zero or numAtoms according to initialValue.; On failure, the previous atom count and selected bits are unchanged.

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ InitialValue

Constructor & Destructor Documentation

◆ AtomSelection() [1/3]

◆ AtomSelection() [2/3]

◆ AtomSelection() [3/3]

Member Function Documentation

◆ clear()

◆ contains()

◆ fill()

◆ getAtomIndices()

◆ getNumAtoms()

◆ getNumSelected()

◆ operator&=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator|=()

◆ set()

◆ setNumAtoms()