An object to complement a topology and hold positions, velocities, and forces of all particles in a system. This is not designed to be the most performant representation of the system's structure. Rather, it serves to hold a high-precision representation of a single system and transport it between CPUs and high-performance accelerators. More...

#include <phasespace.h>

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

	PhaseSpace (PhaseSpace &&original)
	The move constructor prepares the original PhaseSpace object for destruction.

PhaseSpace &	operator= (PhaseSpace &&other)
	The move assignment operator looks much like the copy assignment operator.

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

HybridFormat	getFormat () const
	Get the Hybrid format taken by the object, indicating on which resources its memory is present.

std::string	getFileName () const
	Get the name of the file associated with this object.

int	getAtomCount () const
	Get the number of atoms (particles, including virtual sites) in the object.

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

CoordinateCycle	getCyclePosition () const
	Get the time cycle stage indicating the arrays holding current coordinates.

void	exportToFile (const std::string &file_name, double current_time=0.0, TrajectoryKind traj_kind=TrajectoryKind::POSITIONS, CoordinateFileKind output_kind=CoordinateFileKind::AMBER_INPCRD, PrintSituation expectation=PrintSituation::UNKNOWN) const
	Put the phase space data into a trajectory or checkpoint file.

const PhaseSpace *	getSelfPointer () const
	Get a pointer to the object itself (useful when the object has been passed as a const reference and a pointer is needed).


	PhaseSpace (int atom_count_in=0, UnitCellType unit_cell_in=UnitCellType::NONE, HybridFormat format_in=default_hpc_format)
	Construction of a phase space object, like a topology, is typically done from a file.

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

	PhaseSpace (const std::string &file_name_in, const AtomGraph &ag, CoordinateFileKind file_kind=CoordinateFileKind::UNKNOWN, int frame_number=0, HybridFormat format_in=default_hpc_format)

	PhaseSpace (const std::vector< PhaseSpace * > &input_crd, const std::vector< AtomGraph * > &input_top, const std::vector< int > &counts)

	PhaseSpace (const PhaseSpace ps_a, const AtomGraph ag_a, const PhaseSpace ps_b, const AtomGraph ag_b)

	PhaseSpace (const PhaseSpace &ps_a, const AtomGraph &ag_a, const PhaseSpace &ps_b, const AtomGraph &ag_b)

	PhaseSpace (const PhaseSpace &original, const std::vector< int > &atom_list, HybridFormat format_in=default_hpc_format)

	PhaseSpace (const PhaseSpace &original, const std::vector< uint > &mask, HybridFormat format_in=default_hpc_format)


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

	PhaseSpace (const PhaseSpace &original, HybridFormat format_in)


template<typename T>
void	fill (const T xcrd, const T ycrd, const T zcrd, TrajectoryKind kind=TrajectoryKind::POSITIONS, CoordinateCycle cycle_in=CoordinateCycle::WHITE, 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, TrajectoryKind kind=TrajectoryKind::POSITIONS, CoordinateCycle cycle_in=CoordinateCycle::WHITE, int scale_bits=0, const std::vector< double > &box_dims={})


const double *	getCoordinatePointer (CartesianDimension dim, TrajectoryKind kind, CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get a pointer to the particle X, Y, or Z coordinates, velocities, or forces, on either the host or device. Use this when the entire abstract is unnecessary or would be inefficient to retrieve.

double *	getCoordinatePointer (CartesianDimension dim, TrajectoryKind kind, CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)

const double *	getCoordinatePointer (CartesianDimension dim, TrajectoryKind kind=TrajectoryKind::POSITIONS, HybridTargetLevel tier=HybridTargetLevel::HOST) const

double *	getCoordinatePointer (CartesianDimension dim, TrajectoryKind kind=TrajectoryKind::POSITIONS, HybridTargetLevel tier=HybridTargetLevel::HOST)

const double *	getCoordinatePointer (CartesianDimension dim, CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST) const

double *	getCoordinatePointer (CartesianDimension dim, CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)


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

std::vector< double >	getInterlacedCoordinates (CoordinateCycle orientation, TrajectoryKind kind=TrajectoryKind::POSITIONS, HybridTargetLevel tier=HybridTargetLevel::HOST) const

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

std::vector< double >	getInterlacedCoordinates (int low_index, int high_index, CoordinateCycle orientation, TrajectoryKind kind=TrajectoryKind::POSITIONS, HybridTargetLevel tier=HybridTargetLevel::HOST) const


const double *	getBoxSpaceTransformPointer (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get a pointer to the box space transformation matrix that can track its evolution in the PhaseSpace object's Hybrid data arrays, on either the host or device.

double *	getBoxSpaceTransformPointer (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)

const double *	getBoxSpaceTransformPointer (HybridTargetLevel tier=HybridTargetLevel::HOST) const

double *	getBoxSpaceTransformPointer (HybridTargetLevel tier=HybridTargetLevel::HOST)


const double *	getInverseTransformPointer (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get a pointer to the inverse (back to real space) transformation matrix that can track its evolution in the PhaseSpace object's Hybrid data arrays, on either the host or device.

double *	getInverseTransformPointer (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)

const double *	getInverseTransformPointer (HybridTargetLevel tier=HybridTargetLevel::HOST) const

double *	getInverseTransformPointer (HybridTargetLevel tier=HybridTargetLevel::HOST)


const double *	getBoxSizePointer (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST) const
	Get a pointer to the box dimensions that can track its evolution in the PhaseSpace object's Hybrid data arrays, on either the host or device.

double *	getBoxSizePointer (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)

const double *	getBoxSizePointer (HybridTargetLevel tier=HybridTargetLevel::HOST) const

double *	getBoxSizePointer (HybridTargetLevel tier=HybridTargetLevel::HOST)


std::vector< double >	getBoxSpaceTransform (CoordinateCycle orientation, 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 >	getBoxSpaceTransform (HybridTargetLevel tier=HybridTargetLevel::HOST) const


std::vector< double >	getInverseTransform (CoordinateCycle orientation, 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 >	getInverseTransform (HybridTargetLevel tier=HybridTargetLevel::HOST) const


const Hybrid< double > *	getCoordinateHandle (CartesianDimension dim, TrajectoryKind kind, CoordinateCycle orientation) const
	Get a pointer to one of the coordinate arrays, a pointer to a POINTER-kind Hybrid object.

const Hybrid< double > *	getCoordinateHandle (CartesianDimension dim, TrajectoryKind kind=TrajectoryKind::POSITIONS) const

Hybrid< double > *	getCoordinateHandle (CartesianDimension dim, TrajectoryKind kind, CoordinateCycle orientation)

Hybrid< double > *	getCoordinateHandle (CartesianDimension dim, TrajectoryKind kind=TrajectoryKind::POSITIONS)


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

const Hybrid< double > *	getBoxTransformHandle () const

Hybrid< double > *	getBoxTransformHandle (CoordinateCycle orientation)

Hybrid< double > *	getBoxTransformHandle ()


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

const Hybrid< double > *	getInverseTransformHandle () const

Hybrid< double > *	getInverseTransformHandle (CoordinateCycle orientation)

Hybrid< double > *	getInverseTransformHandle ()


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

const Hybrid< double > *	getBoxDimensionsHandle () const

Hybrid< double > *	getBoxDimensionsHandle (CoordinateCycle orientation)

Hybrid< double > *	getBoxDimensionsHandle ()


const Hybrid< double > *	getStorageHandle () const
	Get a pointer to the ARRAY-kind Hybrid object that holds the actual data. Needed by CoordinateFrame objects which want to be pointers into a PhaseSpace object.

Hybrid< double > *	getStorageHandle ()


void	initializeForces (CoordinateCycle orientation)
	Initialize the forces (set them to zero)

void	initializeForces ()


void	updateCyclePosition ()
	Update the cycle position.

void	updateCyclePosition (CoordinateCycle time_point)


const PhaseSpaceReader	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.

const PhaseSpaceReader	data (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST) const

PhaseSpaceWriter	data (HybridTargetLevel tier=HybridTargetLevel::HOST)

PhaseSpaceWriter	data (CoordinateCycle orientation, HybridTargetLevel tier=HybridTargetLevel::HOST)

Detailed Description

An object to complement a topology and hold positions, velocities, and forces of all particles in a system. This is not designed to be the most performant representation of the system's structure. Rather, it serves to hold a high-precision representation of a single system and transport it between CPUs and high-performance accelerators.

Constructor & Destructor Documentation

◆ PhaseSpace() [1/3]

stormm::trajectory::PhaseSpace::PhaseSpace	(	int	atom_count_in = 0,
		UnitCellType	unit_cell_in = UnitCellType::NONE,
		HybridFormat	format_in = default_hpc_format )

Construction of a phase space object, like a topology, is typically done from a file.

Overloaded:

Constructor fot an object with a number of atoms but no other information (assists in delegation of initialization)
Constructors for coordinate sets read from trajectory or restart files, with the option of a specific frame number (if unspecified, the first frame is read). A topology may also be specified to check the atom count and sanity of the coordinates presented.
Constructors for combining PhaseSpace objects from multiple existing objects

Parameters

file_name	Name of the file from which to obtain coordinates
file_kind	The type of coordinate-containing input file
ag_reference	Topology with which to check atom count, proximity of bonded atoms, and sanity of bond angles (optional)
caller	Name of the calling function (to help backtrace errors)

◆ PhaseSpace() [2/3]

stormm::trajectory::PhaseSpace::PhaseSpace ( const PhaseSpace & 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

◆ PhaseSpace() [3/3]

stormm::trajectory::PhaseSpace::PhaseSpace ( PhaseSpace && original )

The move constructor prepares the original PhaseSpace object for destruction.

Parameters

original The PhaseSpace object from which to preserve content

Member Function Documentation

◆ buildFromFile()

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

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

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)

◆ data()

const PhaseSpaceReader stormm::trajectory::PhaseSpace::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 PhaseSpace object
Get a writeable abstract from a mutable PhaseSpace object
Get either object oriented with the present, alternate positional arrays set as holding the current coordinates (three such abstracts can be rotated over successive cycles of dynamics to let the coordinates evolve, protected against race conditions, without swapping the actual locations in memory)

Parameters

tier	Specify pointers on the host or device
orientation	Arbitrarily selected point on the time cycle to have the reader or writer take as the current coordinates

◆ exportToFile()

void stormm::trajectory::PhaseSpace::exportToFile	(	const std::string &	file_name,
		double	current_time = 0.0,
		TrajectoryKind	traj_kind = TrajectoryKind::POSITIONS,
		CoordinateFileKind	output_kind = CoordinateFileKind::AMBER_INPCRD,
		PrintSituation	expectation = PrintSituation::UNKNOWN ) const

Put the phase space data into a trajectory or checkpoint file.

Parameters

file_name	Name of the file to write
current_time	Time progress of the simulation
traj_kind	The type of trajectory to print (coordinates, velocities, or forces)
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

◆ fill()

template<typename T>

void stormm::trajectory::PhaseSpace::fill	(	const T *	xcrd,
		const T *	ycrd,
		const T *	zcrd,
		TrajectoryKind	kind = TrajectoryKind::POSITIONS,
		CoordinateCycle	cycle_in = CoordinateCycle::WHITE,
		int	scale_bits = 0,
		const double *	box_dims = nullptr )

Fill the object from information in three arrays.

Overloaded:

Fill from three C-style arrays
Fill from three Standard Template Library vector 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

◆ getBoxSizePointer()

const double * stormm::trajectory::PhaseSpace::getBoxSizePointer	(	CoordinateCycle	orientation,
		HybridTargetLevel	tier = HybridTargetLevel::HOST ) const

Get a pointer to the box dimensions that can track its evolution in the PhaseSpace object's Hybrid data arrays, on either the host or device.

Overloaded:

Get a const pointer for a const PhaseSpace object's data
Get a non-const pointer to a mutable PhaseSpace object's data
Indicate a specific point in the time cycle, or accept whatever the object sees as its own current stage of the cycle

Parameters

orientation	A specific point in the time cycle to query
tier	Level at which to extract the data

◆ getBoxSpaceTransform()

std::vector< double > stormm::trajectory::PhaseSpace::getBoxSpaceTransform	(	CoordinateCycle	orientation,
		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.

Overloaded:

Indicate a specific point in the time cycle
Accept whatever the object sees as its own current stage of the cycle

Parameters

orientation	A specific point in the time cycle to query
tier	Level at which to retrieve the data (if STORMM is compiled to run on a GPU)

◆ getBoxSpaceTransformPointer()

const double * stormm::trajectory::PhaseSpace::getBoxSpaceTransformPointer	(	CoordinateCycle	orientation,
		HybridTargetLevel	tier = HybridTargetLevel::HOST ) const

Get a pointer to the box space transformation matrix that can track its evolution in the PhaseSpace object's Hybrid data arrays, on either the host or device.

Overloaded:

Get a const pointer for a const PhaseSpace object's data
Get a non-const pointer to a mutable PhaseSpace object's data
Indicate a specific point in the time cycle, or accept whatever the object sees as its own current stage of the cycle

Parameters

orientation	A specific point in the time cycle to query
tier	Level at which to extract the data

◆ getCoordinateHandle()

const Hybrid< double > * stormm::trajectory::PhaseSpace::getCoordinateHandle	(	CartesianDimension	dim,
		TrajectoryKind	kind,
		CoordinateCycle	orientation ) const

Get a pointer to one of the coordinate arrays, a pointer to a POINTER-kind Hybrid object.

Overloaded:

Specify a stage in the time cycle at which to query coordinates. This may be necessary, step by step, as the object advances in its time cycle.
Accept coordinates from the object's current point in the time cycle. The pointer will remain set to this array even if the PhaseSpace object later advances in its time cycle.
Get a const pointer to data within a const object, or a non-const pointer to data in a mutable object.

Parameters

dim	Indicate Cartesian X, Y, or Z values
kind	Indicate positions, velocities, or forces
orientation	The point in the time cycle (WHITE or BLACK) at which to set the pointer

◆ getCoordinatePointer()

const double * stormm::trajectory::PhaseSpace::getCoordinatePointer	(	CartesianDimension	dim,
		TrajectoryKind	kind,
		CoordinateCycle	orientation,
		HybridTargetLevel	tier = HybridTargetLevel::HOST ) const

Get a pointer to the particle X, Y, or Z coordinates, velocities, or forces, on either the host or device. Use this when the entire abstract is unnecessary or would be inefficient to retrieve.

Overloaded:

Get a const pointer for a const PhaseSpace object's data
Get a non-const pointer to a mutable PhaseSpace object's data
Specify the cycle position, or assume that the object's current position in the time cycle is desired

Parameters

dim	Cartesian dimension of interest
kind	Specify coordinates, velocities, or forces–anything that could be thought of as a trajectory
tier	Level at which to extract the data

◆ getInterlacedCoordinates()

std::vector< double > stormm::trajectory::PhaseSpace::getInterlacedCoordinates	(	TrajectoryKind	kind = TrajectoryKind::POSITIONS,
		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
Choose the point in the time cycle or accept the object's "current" state

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::PhaseSpace::getInverseTransform	(	CoordinateCycle	orientation,
		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

orientation	A specific point in the time cycle to query
tier	Level at which to retrieve the data (if STORMM is compiled to run on a GPU)

◆ getInverseTransformPointer()

const double * stormm::trajectory::PhaseSpace::getInverseTransformPointer	(	CoordinateCycle	orientation,
		HybridTargetLevel	tier = HybridTargetLevel::HOST ) const

Get a pointer to the inverse (back to real space) transformation matrix that can track its evolution in the PhaseSpace object's Hybrid data arrays, on either the host or device.

Overloaded:

Get a const pointer for a const PhaseSpace object's data
Get a non-const pointer to a mutable PhaseSpace object's data
Indicate a specific point in the time cycle, or accept whatever the object sees as its own current stage of the cycle

Parameters

orientation	A specific point in the time cycle to query
tier	Level at which to extract the data

◆ getStorageHandle()

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

Get a pointer to the ARRAY-kind Hybrid object that holds the actual data. Needed by CoordinateFrame objects which want to be pointers into a PhaseSpace object.

Overloaded:

Get a const pointer to a const PhaseSpace object's data storage
Get a non-const pointer to a mutable PhaeSpace object's data storage

◆ initializeForces()

void stormm::trajectory::PhaseSpace::initializeForces ( CoordinateCycle orientation )

Initialize the forces (set them to zero)

Overloaded:

Update forces for an arbitrary point in the time cycle
Update forces for the object's current position in the cycle

Parameters

orentation A selected point in the time cycle (WHITE or BLACK)

◆ operator=() [1/2]

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

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

Parameters

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

◆ operator=() [2/2]

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

The move assignment operator looks much like the copy assignment operator.

Parameters

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

◆ updateCyclePosition()

void stormm::trajectory::PhaseSpace::updateCyclePosition ( )

Update the cycle position.

Overloaded:

Advance the cycle position based on its current setting (no input argument): present >> future >> past >> present >> ...
Set the cycle position to an arbitrary point

Parameters

time_point The point in the time cycle that shall become the PhaseSpace object's "present" coordinates.

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

src/Trajectory/phasespace.h
src/Trajectory/phasespace.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ PhaseSpace() [1/3]

◆ PhaseSpace() [2/3]

◆ PhaseSpace() [3/3]

Member Function Documentation

◆ buildFromFile()

◆ data()

◆ exportToFile()

◆ fill()

◆ getBoxSizePointer()

◆ getBoxSpaceTransform()

◆ getBoxSpaceTransformPointer()

◆ getCoordinateHandle()

◆ getCoordinatePointer()

◆ getInterlacedCoordinates()

◆ getInverseTransform()

◆ getInverseTransformPointer()

◆ getStorageHandle()

◆ initializeForces()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ updateCyclePosition()