Store the coordinates and box information for a frame, only. This abridged struct can serve when the full PhaseSpace object would allocate too much memory. It also comes with its own POINTER mode, such that it allocates no memory of its own and merely points to another CoordinateFrame object or PhaseSpace object that does have memory allocated. More...

#include <coordinateframe.h>

Public Member Functions
CoordinateFrame &	operator= (const CoordinateFrame &other)
	Copy assignment operator likewise handles reassignment of internal POINTER-kind Hybrid objects.

	CoordinateFrame (CoordinateFrame &&original)
	Move constructor works in similar fashion to the PhaseSpace move constructor, with std::move and no need for reassignment of the underlying POINTER-kind Hybrid objects.

CoordinateFrame &	operator= (CoordinateFrame &&other)
	Move assignment operator.

HybridFormat	getFormat () const
	Get the format of the object.

std::string	getFileName () const
	Get the file name that originated this coordinate set.

int	getFrameNumber () const
	Get the frame number, if this coordinate set originated in a trajectory.

int	getAtomCount () const
	Get the number of atoms in the frame.

UnitCellType	getUnitCellType () const
	Get the unit cell type of the coordinate system.

std::vector< double >	getBoxSpaceTransform (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the transformation matrix to take coordinates into box (fractional) space. The result should be interpreted as a 3x3 matrix in column-major format.

std::vector< double >	getInverseTransform (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the transformation matrix to take coordinates from fractional space back into real space. The result should be interpreted as a 3x3 matrix in column-major format.

std::vector< double >	getBoxDimensions (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the box dimensions in their pure form. Holding the box dimensions and the transformation matrices they imply in separate member variables represents a liability, that they might at some point become inconsistent, but it also prevents having to continuously extract box dimensions from transformation matrices each time the box needs to be resized (beyond isotropic scaling, this is not a trivial process).

const CoordinateFrame *	getSelfPointer () const
	Get a pointer to the object itself, useful when working with a const reference.

void	exportToFile (const std::string &file_name, CoordinateFileKind output_kind=CoordinateFileKind::AMBER_CRD, PrintSituation expectation=PrintSituation::UNKNOWN, HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Export the contents of this coordinate series to a trajectory, restart, or input coordinates file.

void	setFrameNumber (int frame_number_in)
	Set the frame number, for bookkeeping purposes. This function exists that the frame number does not become a necessary argument in one of the overloaded constructors.


	CoordinateFrame (int natom_in=0, UnitCellType unit_cell_in=UnitCellType::NONE, HybridFormat format_in=default_hpc_format)
	There are several options for construction of this abridged, coordinate-only object.

	CoordinateFrame (int natom_in, UnitCellType unit_cell_in, const double xcrd_in, const double ycrd_in, const double zcrd_in, const double umat_in=nullptr, const double invu_in=nullptr, const double boxdim_in=nullptr, HybridFormat format_in=default_hpc_format)

	CoordinateFrame (const std::string &file_name_in, CoordinateFileKind file_kind=CoordinateFileKind::UNKNOWN, int frame_number_in=0, HybridFormat format_in=default_hpc_format)

	CoordinateFrame (const TextFile &tf, CoordinateFileKind file_kind=CoordinateFileKind::UNKNOWN, int frame_number_in=0, HybridFormat format_in=default_hpc_format)

	CoordinateFrame (const PhaseSpace *ps)

	CoordinateFrame (const PhaseSpace &ps)


	CoordinateFrame (const CoordinateFrame &original)
	The copy constructor handles assignment of internal POINTER-kind Hybrid objects.

	CoordinateFrame (const CoordinateFrame &original, HybridFormat format_in)


void	buildFromFile (const std::string &file_name_in, const CoordinateFileKind file_kind, int frame_number=0)
	Fill the object from information some coordinate, restart, or trajectory file.

void	buildFromFile (const TextFile &tf, const CoordinateFileKind file_kind, int frame_number=0)


template<typename T>
void	fill (const T xcrd, const T ycrd, const T zcrd, int scale_bits=0, const double box_dims=nullptr)
	Fill the object from information in three arrays.

template<typename T>
void	fill (const std::vector< T > &xcrd, const std::vector< T > &ycrd, const std::vector< T > &zcrd, int scale_bits=0, const std::vector< double > &box_dims={})


std::vector< double >	getInterlacedCoordinates (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the coordinates returned in an X/Y/Z interlaced manner.

std::vector< double >	getInterlacedCoordinates (int low_index, int high_index, HybridTargetLevel tier=HybridTargetLevel::HOST) const


const Hybrid< double > *	getCoordinateHandle (CartesianDimension dim) const
	Get a pointer to one of the coordinate arrays.

Hybrid< double > *	getCoordinateHandle (CartesianDimension dim)


const Hybrid< double > *	getBoxTransformHandle () const
	Get a pointer to the box space transform. Overloading follows from getCoordinateHandle(), above.

Hybrid< double > *	getBoxTransformHandle ()


const Hybrid< double > *	getInverseTransformHandle () const
	Get a pointer to the inverse transform that takes coordinates back into real space. Overloading follows from getCoordinateHandle(), above.

Hybrid< double > *	getInverseTransformHandle ()


const Hybrid< double > *	getBoxDimensionsHandle () const
	Get a pointer to the transform that takes coordinates back into real space. Overloading follows from getCoordinateHandle(), above.

Hybrid< double > *	getBoxDimensionsHandle ()


const Hybrid< double > *	getStorageHandle () const
	Get a pointer to the storage array accessible outside the object.

Hybrid< double > *	getStorageHandle ()


const CoordinateFrameReader	data (HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get the abstract for this object, containing C-style pointers for the most rapid access to any of its member variables.

CoordinateFrameWriter	data (HybridTargetLevel tier=HybridTargetLevel::HOST)

Detailed Description

Store the coordinates and box information for a frame, only. This abridged struct can serve when the full PhaseSpace object would allocate too much memory. It also comes with its own POINTER mode, such that it allocates no memory of its own and merely points to another CoordinateFrame object or PhaseSpace object that does have memory allocated.

Constructor & Destructor Documentation

◆ CoordinateFrame() [1/3]

stormm::trajectory::CoordinateFrame::CoordinateFrame	(	int	natom_in = 0,
		UnitCellType	unit_cell_in = UnitCellType::NONE,
		HybridFormat	format_in = default_hpc_format )

There are several options for construction of this abridged, coordinate-only object.

Overloaded:

Allocate to hold a given number of atoms
From an atom count and a set of double-precision C-style arrays, including coordinates and box dimensions
Create from any of the coordinate file formats (velocities will not be read, even if they are available)
From an existing PhaseSpace object (as a pointer or a copy if the PhaseSpace object is non-const, otherwise only as a copy)

Parameters

natom_in	The number of atoms expected
xcrd_in	Cartesian X coordinates of all particles
ycrd_in	Cartesian Y coordinates of all particles
zcrd_in	Cartesian Z coordinates of all particles
umat_in	Matrix to transform coordinates into box space (3 x 3)
invu_in	Matrix to transform coordinates into real space (3 x 3)
file_name_in	File to read from
file_kind	The type of coordinate file to expect
frame_number_in	Frame number of the file to read (default 0, the first frame)
ps	Pre-existing object with complete description of the system state

◆ CoordinateFrame() [2/3]

stormm::trajectory::CoordinateFrame::CoordinateFrame ( const CoordinateFrame & original )

The copy constructor handles assignment of internal POINTER-kind Hybrid objects.

Overloaded:

Take the original object's memory layout
Apply an alternate memory layout. The content will be determined by whatever content is available in the original object at each tier of memory: if the new object is to have a memory component on the GPU device and the original object also has a memory component on the GPU, then this is the state that will be copied over. Otherwise, the original object's data from the CPU host will become the new object's GPU component. This priority of "copy data from what exists at the same level, otherwise take from the other level" applies everywhere.

Parameters

original	The PhaseSpace object from which to make a deep copy
format_in	An alternate memory format in which to lay out the new CoordinateFrame

◆ CoordinateFrame() [3/3]

stormm::trajectory::CoordinateFrame::CoordinateFrame ( CoordinateFrame && original )

Move constructor works in similar fashion to the PhaseSpace move constructor, with std::move and no need for reassignment of the underlying POINTER-kind Hybrid objects.

Parameters

original The PhaseSpace object from which to make a deep copy

Member Function Documentation

◆ buildFromFile()

void stormm::trajectory::CoordinateFrame::buildFromFile	(	const std::string &	file_name_in,
		const CoordinateFileKind	file_kind,
		int	frame_number = 0 )

Fill the object from information some coordinate, restart, or trajectory file.

Overloaded:

Take a file name
Take an ASCII-format text file already processed into RAM

Parameters

file_name	Name of the file from which to obtain coordinates
file_kind	The type of coordinate-containing input file
frame_number	The frame number to read (if the file is a trajectory, not a single point from the system's phase space)
tf	Text file data already processed into RAM

◆ data()

const CoordinateFrameReader stormm::trajectory::CoordinateFrame::data ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Get the abstract for this object, containing C-style pointers for the most rapid access to any of its member variables.

Overloaded:

Get a read-only abstract from a const object
Get a writeable abstract from a mutable object

◆ exportToFile()

void stormm::trajectory::CoordinateFrame::exportToFile	(	const std::string &	file_name,
		CoordinateFileKind	output_kind = CoordinateFileKind::AMBER_CRD,
		PrintSituation	expectation = PrintSituation::UNKNOWN,
		HybridTargetLevel	tier = HybridTargetLevel::HOST ) const

Export the contents of this coordinate series to a trajectory, restart, or input coordinates file.

Parameters

file_name	Name of the file to write
output_kind	The format of the file to write (checkpoint files print position and velocity data by obligation, but trajectory files can contain either of these as well as forces)
expectation	The condition in which the output file is expected to be found
tier	Indicate whether to obtain data on the CPU host or GPU device. To print GPU-based coordinates will not alter data on the CPU host.

◆ fill()

template<typename T>

void stormm::trajectory::CoordinateFrame::fill	(	const T *	xcrd,
		const T *	ycrd,
		const T *	zcrd,
		int	scale_bits = 0,
		const double *	box_dims = nullptr )

Fill the object from information in three arrays.

Overloaded:

Fill from a collection of C-style arrays
Fill from a collection of Standard Template Library vector objects
Fill from a collection of Hybrid objects

Parameters

xcrd	Cartesian X coordinates of positions, velocities, or forces
ycrd	Cartesian Y coordinates of positions, velocities, or forces
zcrd	Cartesian Z coordinates of positions, velocities, or forces
kind	Type of coordinates coming in: fill the positions, velocities, or forces
cycle_in	The point in the coordinate cycle to fill
scale_bits	The number of bits after the decimal, applicable to fixed-precision representations of xcrd, ycrd, and zcrd (the box dimensions are always given as a double-precision array, in units of Angstroms)
box_dims	Box dimensions, from which the tranformation matrices will be derived

◆ getBoxDimensions()

std::vector< double > stormm::trajectory::CoordinateFrame::getBoxDimensions ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Get the box dimensions in their pure form. Holding the box dimensions and the transformation matrices they imply in separate member variables represents a liability, that they might at some point become inconsistent, but it also prevents having to continuously extract box dimensions from transformation matrices each time the box needs to be resized (beyond isotropic scaling, this is not a trivial process).

Parameters

tier	Level at which to retrieve the data (if STORMM is compiled to run on a GPU)

◆ getBoxSpaceTransform()

std::vector< double > stormm::trajectory::CoordinateFrame::getBoxSpaceTransform ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Get the transformation matrix to take coordinates into box (fractional) space. The result should be interpreted as a 3x3 matrix in column-major format.

Parameters

tier	Level at which to retrieve the data (if STORMM is compiled to run on a GPU)

◆ getCoordinateHandle()

const Hybrid< double > * stormm::trajectory::CoordinateFrame::getCoordinateHandle ( CartesianDimension dim ) const

Get a pointer to one of the coordinate arrays.

Overloaded:

Get a const pointer to the storage array of a const object
Get a non-const pointer to the storage space of a mutable object.

Parameters

dim	Specify coordinate data along one of the Cartesian axes

◆ getInterlacedCoordinates()

std::vector< double > stormm::trajectory::CoordinateFrame::getInterlacedCoordinates ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Get the coordinates returned in an X/Y/Z interlaced manner.

Overloaded:

Get all coordinates
Get coordinates for a range of atoms

Parameters

low_index	The lower atom index of a range
high_index	The upper atom index of a range
kind	Specify coordinates, velocities, or forces–anything that could be thought of as a trajectory
tier	Level at which to extract the data

◆ getInverseTransform()

std::vector< double > stormm::trajectory::CoordinateFrame::getInverseTransform ( HybridTargetLevel tier = HybridTargetLevel::HOST ) const

Get the transformation matrix to take coordinates from fractional space back into real space. The result should be interpreted as a 3x3 matrix in column-major format.

Parameters

tier	Level at which to retrieve the data (if STORMM is compiled to run on a GPU)

◆ getStorageHandle()

const Hybrid< double > * stormm::trajectory::CoordinateFrame::getStorageHandle ( ) const

Get a pointer to the storage array accessible outside the object.

Overloaded:

Get a const pointer to the storage array of a const object
Get a non-const pointer to the storage space of a mutable object.

◆ operator=() [1/2]

CoordinateFrame & stormm::trajectory::CoordinateFrame::operator= ( const CoordinateFrame & other )

Copy assignment operator likewise handles reassignment of internal POINTER-kind Hybrid objects.

Parameters

other Another way to say original, in a different semantic context

◆ operator=() [2/2]

CoordinateFrame & stormm::trajectory::CoordinateFrame::operator= ( CoordinateFrame && other )

Move assignment operator.

Parameters

other Another way to say original, in a different semantic context

◆ setFrameNumber()

void stormm::trajectory::CoordinateFrame::setFrameNumber ( int frame_number_in )

Set the frame number, for bookkeeping purposes. This function exists that the frame number does not become a necessary argument in one of the overloaded constructors.

Parameters

frame_number_in The (arbitrary) number to set the frame as

The documentation for this class was generated from the following files:

src/Trajectory/coordinateframe.h
src/Trajectory/coordinateframe.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CoordinateFrame() [1/3]

◆ CoordinateFrame() [2/3]

◆ CoordinateFrame() [3/3]

Member Function Documentation

◆ buildFromFile()

◆ data()

◆ exportToFile()

◆ fill()

◆ getBoxDimensions()

◆ getBoxSpaceTransform()

◆ getCoordinateHandle()

◆ getInterlacedCoordinates()

◆ getInverseTransform()

◆ getStorageHandle()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ setFrameNumber()