Coordinates Class Reference

Owns host-resident Cartesian coordinates in two precisions. More...

#include <Coordinates.h>

Inheritance diagram for Coordinates:

Public Member Functions
	Coordinates (void)
	Constructs an unset coordinate object.
	Coordinates (const std::vector< double3 > &coords)
	Constructs both representations from double-precision coordinates.
	Coordinates (const std::vector< float3 > &coords)
	Constructs both representations from single-precision coordinates.
	Coordinates (const std::vector< std::vector< double > > &coords)
	Constructs both representations from nested double rows.
	Coordinates (const std::vector< std::vector< float > > &coords)
	Constructs both representations from nested float rows.
void	setNumAtoms (const int numAtoms)
	Sets the atom count and resizes both coordinate vectors.
int	getNumAtoms (void) const
	Returns the stored atom count.
const std::vector< double3 > &	getCoordinatesDP (void) const
	Returns the double-precision coordinate vector.
std::vector< double3 > &	getCoordinatesDP (void)
	Returns mutable double-precision coordinate storage.
const std::vector< float3 > &	getCoordinatesSP (void) const
	Returns the single-precision coordinate vector.
std::vector< float3 > &	getCoordinatesSP (void)
	Returns mutable single-precision coordinate storage.

Protected Attributes
int	m_NumAtoms
std::vector< double3 >	m_CoordinatesDP
std::vector< float3 >	m_CoordinatesSP

Detailed Description

Owns host-resident Cartesian coordinates in two precisions.

Coordinates stores one double3 record and one float3 record per atom in atom order. Each record contains x, y, and z Cartesian coordinates in angstroms. Both std::vector instances are owned by this object. The class does not allocate CUDA device memory, transfer data, or synchronize a CUDA stream.

Constructors initialize both precision representations from one input. Mutable access through getCoordinatesDP() or getCoordinatesSP() does not update the other representation or the stored atom count. Callers using those escape hatches must preserve the normal invariant that getNumAtoms(), getCoordinatesDP().size(), and getCoordinatesSP().size() describe the same number of atoms.

Default construction represents unset state. Construction from an empty input or a successful setNumAtoms(0) represents an explicitly initialized zero-atom object. Compiler-generated copy operations deep-copy both vectors; compiler-generated move operations transfer their storage. Assignment or resizing can change the vector contents and invalidate element references, pointers, and iterators.

Warning

The destructor is not virtual. Do not delete a derived CharmmCrd object through a Coordinates pointer.

The class provides no internal synchronization. Externally serialize overlapping access whenever an operation can mutate the object or either returned vector.

See also

coordinates

CharmmContext

Constructor & Destructor Documentation

Coordinates() [1/5]

Coordinates::Coordinates

(

void

)

Constructs an unset coordinate object.

Postcondition

getNumAtoms() == -1.

Both coordinate vectors are empty.

Note

The -1 count is a dimensionless sentinel that distinguishes unset state from an explicitly initialized zero-atom object.

Coordinates() [2/5]

Coordinates::Coordinates

(

const std::vector< double3 > &

coords

)

Constructs both representations from double-precision coordinates.

The double-precision records are copied unchanged. Each component is also converted with static_cast<float> for the single-precision representation. No finiteness or physical-range validation is performed.

Parameters

[in]

coords

Borrowed host vector containing one double3 record per atom in [x, y, z] order and angstrom units. The values are copied and the vector is not retained.

Exceptions

std::bad_alloc	If either owned vector cannot allocate storage.
std::length_error	If an owned vector rejects the requested length.

Precondition

coords.size() is at most INT_MAX because the atom count is stored as int.

Every component is representable as float.

Postcondition

Both owned vectors contain coords.size() records and getNumAtoms() == static_cast<int>(coords.size()).

Coordinates() [3/5]

Coordinates::Coordinates

(

const std::vector< float3 > &

coords

)

Constructs both representations from single-precision coordinates.

The single-precision records are copied unchanged. Each component is also converted to double for the double-precision representation. No finiteness or physical-range validation is performed.

Parameters

[in]

coords

Borrowed host vector containing one float3 record per atom in [x, y, z] order and angstrom units. The values are copied and the vector is not retained.

Exceptions

std::bad_alloc	If either owned vector cannot allocate storage.
std::length_error	If an owned vector rejects the requested length.

Precondition

coords.size() is at most INT_MAX because the atom count is stored as int.

Postcondition

Both owned vectors contain coords.size() records and getNumAtoms() == static_cast<int>(coords.size()).

Coordinates() [4/5]

Coordinates::Coordinates

(

const std::vector< std::vector< double > > &

coords

)

Constructs both representations from nested double rows.

Each outer element represents one atom and must contain exactly three values in [x, y, z] order. Values use angstroms. Double values are copied to double3 records and converted with static_cast<float> for the float3 records.

Parameters

[in]

coords

Borrowed host rows in atom order. All values are copied and no row or outer-vector storage is retained.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if any row does not contain exactly three values.
std::bad_alloc	If vector or error-diagnostic storage cannot be allocated.
std::length_error	If a vector or diagnostic exceeds an implementation limit.

Precondition

coords.size() is at most INT_MAX because the atom count is stored as int.

Every component is representable as float.

Postcondition

Both owned vectors contain coords.size() records and getNumAtoms() == static_cast<int>(coords.size()).

Coordinates() [5/5]

Coordinates::Coordinates

(

const std::vector< std::vector< float > > &

coords

)

Constructs both representations from nested float rows.

Each outer element represents one atom and must contain exactly three values in [x, y, z] order. Values use angstroms. Float values are copied to float3 records and converted to double for the double3 records.

Parameters

[in]

coords

Borrowed host rows in atom order. All values are copied and no row or outer-vector storage is retained.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if any row does not contain exactly three values.
std::bad_alloc	If vector or error-diagnostic storage cannot be allocated.
std::length_error	If a vector or diagnostic exceeds an implementation limit.

Precondition

coords.size() is at most INT_MAX because the atom count is stored as int.

Postcondition

Both owned vectors contain coords.size() records and getNumAtoms() == static_cast<int>(coords.size()).

Member Function Documentation

getCoordinatesDP() [1/2]

std::vector< double3 > & Coordinates::getCoordinatesDP

(

void

)

Returns mutable double-precision coordinate storage.

Returns

A borrowed mutable reference to the owned host vector. Each double3 is one atom in [x, y, z] order and angstrom units. The vector reference remains valid for the lifetime of this object. Element references, pointers, and iterators follow std::vector invalidation rules.

Warning

Mutation is unchecked. Changing values does not update the single-precision vector, and changing the vector length does not update m_NumAtoms or the single-precision vector.

getCoordinatesDP() [2/2]

const std::vector< double3 > & Coordinates::getCoordinatesDP

(

void

)

const

Returns the double-precision coordinate vector.

Returns

A borrowed read-only reference to the owned host vector. Each double3 is one atom in [x, y, z] order and angstrom units. The vector reference remains valid for the lifetime of this object. Element references, pointers, and iterators follow std::vector invalidation rules.

Note

This call performs no copy, precision conversion, CUDA transfer, or synchronization.

getCoordinatesSP() [1/2]

std::vector< float3 > & Coordinates::getCoordinatesSP

(

void

)

Returns mutable single-precision coordinate storage.

Returns

A borrowed mutable reference to the owned host vector. Each float3 is one atom in [x, y, z] order and angstrom units. The vector reference remains valid for the lifetime of this object. Element references, pointers, and iterators follow std::vector invalidation rules.

Warning

Mutation is unchecked. Changing values does not update the double-precision vector, and changing the vector length does not update m_NumAtoms or the double-precision vector.

getCoordinatesSP() [2/2]

const std::vector< float3 > & Coordinates::getCoordinatesSP

(

void

)

const

Returns the single-precision coordinate vector.

Returns

A borrowed read-only reference to the owned host vector. Each float3 is one atom in [x, y, z] order and angstrom units. The vector reference remains valid for the lifetime of this object. Element references, pointers, and iterators follow std::vector invalidation rules.

Note

This call performs no copy, precision conversion, CUDA transfer, or synchronization.

getNumAtoms()

int Coordinates::getNumAtoms

(

void

)

const

Returns the stored atom count.

Returns

-1 for the default-constructed unset state, or a non-negative dimensionless count after successful initialization.

Note

The value is stored independently and is not recomputed from either vector after mutable access.

setNumAtoms()

void Coordinates::setNumAtoms

(

const int

numAtoms

)

Sets the atom count and resizes both coordinate vectors.

Existing elements in the retained prefix are preserved. New elements are value-initialized by std::vector::resize. This host-only operation does not transfer coordinates to a CUDA device or update another object.

Parameters

[in]

numAtoms

Dimensionless atom count. The value must be non-negative.

Exceptions

ApoCharmmError	With code ApoCharmmErrorCode::InvalidArgument if numAtoms is negative.
std::bad_alloc	If either vector cannot allocate storage.
std::length_error	If either vector rejects the requested length.

Postcondition

On success, getNumAtoms() == numAtoms and both vector sizes equal static_cast<std::size_t>(numAtoms).

If numAtoms is negative, the object is unchanged.

Warning

Successful reallocation invalidates element references, pointers, and iterators into the affected vector. References to the vector objects themselves remain valid.

The two resizes are sequential rather than transactional. An allocation failure can leave the stored count and vector sizes inconsistent.

Member Data Documentation

m_CoordinatesDP

std::vector<double3> Coordinates::m_CoordinatesDP

protected

Owns double-precision host coordinates in atom-major [x, y, z] order.

m_CoordinatesSP

std::vector<float3> Coordinates::m_CoordinatesSP

protected

Owns single-precision host coordinates in atom-major [x, y, z] order.

m_NumAtoms

int Coordinates::m_NumAtoms

protected

Stores the dimensionless atom count, or -1 for unset state.