Representation of a simulation snapshot file in the VTF format. More...

#include <VTFSnapshotFile.hpp>

Inheritance diagram for OpenMPCD::VTFSnapshotFile:

Collaboration diagram for OpenMPCD::VTFSnapshotFile:

Classes
struct	AtomProperties
	Collection of properties of atoms. More...

Public Member Functions
	VTFSnapshotFile (const std::string &path_)
	The constructor. More...

virtual	~VTFSnapshotFile ()
	The destructor. More...

bool	isInWriteMode () const
	Returns whether the instance is in write mode. More...

bool	isInReadMode () const
	Returns whether the instance is in read mode. More...

bool	structureBlockHasBeenProcessed () const
	Returns whether the structure block has been processed already. More...

void	setPrimarySimulationVolumeSize (const FP &x, const FP &y, const FP &z)
	Sets the size of the primary simulation volume. More...

bool	primarySimulationVolumeSizeIsSet () const
	Returns whether the size of the primary simulation volume is set. More...

const Vector3D< FP > &	getPrimarySimulationVolumeSize () const
	Returns the size of the primary simulation volume. More...

const std::pair< std::size_t, std::size_t >	declareAtoms (const std::size_t count)
	Declares a number of atoms. More...

const std::pair< std::size_t, std::size_t >	declareAtoms (const std::size_t count, const FP radius, const std::string &name, const std::string &type)
	Declares a number of atoms of the same kind. More...

std::size_t	getNumberOfAtoms () const
	Returns the number of atoms that have been declared. More...

bool	isValidAtomID (const std::size_t atomID) const
	Returns whether the given number is a valid atom ID, i.e. More...

const AtomProperties &	getAtomProperties (const std::size_t atomID) const
	Returns the properties of the given `atomID`. More...

void	declareBond (std::size_t atom1, std::size_t atom2)
	Declares a bond between the two given atoms. More...

const std::set< std::pair< std::size_t, std::size_t > > &	getBonds () const
	Returns the set of bonds between atoms. More...

bool	hasBond (std::size_t atom1, std::size_t atom2) const
	Returns whether the two given atoms share a bond. More...

void	writeTimestepBlock (const FP const positions, const FP const velocities=NULL)
	Starts a new timestep block, and writes the atom coordinates given. More...

bool	readTimestepBlock (FP const positions, FP const velocities=NULL, bool *const velocitiesEncountered=NULL)
	Reads the next timestep block. More...

Detailed Description

Representation of a simulation snapshot file in the VTF format.

The VTF format is documented at the following URL: https://github.com/olenz/vtfplugin/wiki/VTF-format

A snapshot file can be opened either in write mode or in read mode. The instance is in read mode if it is passed a path to an existing file, and in write mode otherwise. In read mode, the snapshot cannot be changed (trying to do that results in an instance of OpenMPCD::InvalidCallException being thrown). In write mode, one cannot read data that does not belong to the structure block.

A VTF file starts with up to one structure block, followed by an arbitrary number of timestep blocks. After data that does not belong to the structure block has been supplied, structure block information cannot be changed anymore; any attempts to do so result in an instance of OpenMPCD::InvalidCallException being thrown.

It is not guaranteed that data will be written to the snapshot file immediately. Writes may be cached until the object is destroyed.

Definition at line 49 of file VTFSnapshotFile.hpp.

Constructor & Destructor Documentation

◆ VTFSnapshotFile()

VTFSnapshotFile::VTFSnapshotFile ( const std::string & path_ )

The constructor.

The path_ given will be used to open the snapshot file. If the file does not exist, it will be created, and the instance is in write mode. Otherwise, the instance is in read mode.

Exceptions

OpenMPCD::IOException	Throws if the file could not be opened or created.
OpenMPCD::MalformedFileException	In read mode, throws if the VTF file is malformed.

Parameters

[in] path_ The path to the snapshot file.

Definition at line 19 of file VTFSnapshotFile.cpp.

◆ ~VTFSnapshotFile()

VTFSnapshotFile::~VTFSnapshotFile ( )

virtual

The destructor.

Definition at line 59 of file VTFSnapshotFile.cpp.

Member Function Documentation

◆ declareAtoms() [1/2]

const std::pair< std::size_t, std::size_t > VTFSnapshotFile::declareAtoms ( const std::size_t count )

Declares a number of atoms.

Exceptions

OpenMPCD::InvalidCallException	Throws if the instance is not in write mode.
OpenMPCD::InvalidCallException	Throws if the structure block has already been written.

Parameters

[in] count The number of atoms to declare; if it is 0, nothing happens.

Returns: Returns the ID of the first declared atom as the first value, and the ID of the last declared atom as the second value. If count == 0, the pair {0, 0} is returned.

Definition at line 79 of file VTFSnapshotFile.cpp.

◆ declareAtoms() [2/2]

const std::pair< std::size_t, std::size_t > VTFSnapshotFile::declareAtoms	(	const std::size_t	count,
		const FP	radius,
		const std::string &	name,
		const std::string &	type
	)

Declares a number of atoms of the same kind.

Exceptions

OpenMPCD::InvalidArgumentException Throws if the arguments violate the conditions outlined.

Parameters

[in]	count	The number of atoms to declare; if it is 0, nothing happens.
[in]	radius	The radius of the atoms, which must be greater than or equal to 0, or -1 for default.
[in]	name	The name of the atoms, as a string without whitespace and of length greater than 0 but less than or equal to 16, or empty for default.
[in]	type	The type of the atoms, as a string without whitespace and of length greater than 0 but less than or equal to 16, or empty for default.

Returns: Returns the ID of the first declared atom as the first value, and the ID of the last declared atom as the second value. If count == 0, the pair {0, 0} is returned.

Definition at line 98 of file VTFSnapshotFile.cpp.

◆ declareBond()

void VTFSnapshotFile::declareBond	(	std::size_t	atom1,
		std::size_t	atom2
	)

Declares a bond between the two given atoms.

Exceptions

OpenMPCD::InvalidCallException	Throws if the instance is not in write mode.
OpenMPCD::InvalidCallException	Throws if the structure block has already been written.
OpenMPCD::OutOfBoundsException	Throws if `!isValidAtomID(atom1)` or `!isValidAtomID(atom2)`.
OpenMPCD::InvalidArgumentException	Throws if `atom1 == atom2`.
OpenMPCD::InvalidArgumentException	Throws if a bond between those atoms exists already.

Parameters

[in]	atom1	The ID of the first atom.
[in]	atom2	The ID of the second atom.

Definition at line 152 of file VTFSnapshotFile.cpp.

◆ getAtomProperties()

const VTFSnapshotFile::AtomProperties & VTFSnapshotFile::getAtomProperties ( const std::size_t atomID ) const

Returns the properties of the given atomID.

Exceptions

OpenMPCD::OutOfBoundsException Throws if !isValidAtomID(atomID).

Parameters

[in] atomID The ID of the atom in question.

Definition at line 138 of file VTFSnapshotFile.cpp.

◆ getBonds()

const std::set<std::pair<std::size_t, std::size_t> >& OpenMPCD::VTFSnapshotFile::getBonds ( ) const

inline

Returns the set of bonds between atoms.

Each entry bond of the returned value denotes a bond between the atoms with the IDs bond.first and bond.second, where bond.first < bond.second.

Definition at line 255 of file VTFSnapshotFile.hpp.

◆ getNumberOfAtoms()

std::size_t OpenMPCD::VTFSnapshotFile::getNumberOfAtoms ( ) const

inline

Returns the number of atoms that have been declared.

Definition at line 200 of file VTFSnapshotFile.hpp.

◆ getPrimarySimulationVolumeSize()

const Vector3D<FP>& OpenMPCD::VTFSnapshotFile::getPrimarySimulationVolumeSize ( ) const

inline

Returns the size of the primary simulation volume.

The returned vector holds the Cartesian coordinates.

Exceptions

OpenMPCD::InvalidCallException Throws if !primarySimulationVolumeSizeIsSet().

Definition at line 146 of file VTFSnapshotFile.hpp.

◆ hasBond()

bool VTFSnapshotFile::hasBond	(	std::size_t	atom1,
		std::size_t	atom2
	)		const

Returns whether the two given atoms share a bond.

The order of the arguments does not influence the returned value.

Exceptions

OpenMPCD::OutOfBoundsException	Throws if `!isValidAtomID(atom1)` or `!isValidAtomID(atom2)`.
OpenMPCD::InvalidArgumentException	Throws if `atom1 == atom2`.

Parameters

[in]	atom1	The ID of the first atom.
[in]	atom2	The ID of the second atom.

Definition at line 174 of file VTFSnapshotFile.cpp.

◆ isInReadMode()

bool OpenMPCD::VTFSnapshotFile::isInReadMode ( ) const

inline

Returns whether the instance is in read mode.

Definition at line 96 of file VTFSnapshotFile.hpp.

◆ isInWriteMode()

bool OpenMPCD::VTFSnapshotFile::isInWriteMode ( ) const

inline

Returns whether the instance is in write mode.

Definition at line 88 of file VTFSnapshotFile.hpp.

◆ isValidAtomID()

bool OpenMPCD::VTFSnapshotFile::isValidAtomID ( const std::size_t atomID ) const

inline

Returns whether the given number is a valid atom ID, i.e.

whether atomID < getNumberOfAtoms().

Parameters

[in] atomID The atom ID to check.

Definition at line 214 of file VTFSnapshotFile.hpp.

◆ primarySimulationVolumeSizeIsSet()

bool OpenMPCD::VTFSnapshotFile::primarySimulationVolumeSizeIsSet ( ) const

inline

Returns whether the size of the primary simulation volume is set.

Definition at line 133 of file VTFSnapshotFile.hpp.

◆ readTimestepBlock()

bool VTFSnapshotFile::readTimestepBlock	(	FP *const	positions,
		FP *const	velocities = `NULL`,
		bool *const	velocitiesEncountered = `NULL`
	)

Reads the next timestep block.

Exceptions

OpenMPCD::InvalidCallException	Throws if the instance is not in read mode.
OpenMPCD::UnimplementedException	Throws if the timestep block is not in ordered format.
OpenMPCD::MalformedFileException	Throws if in the timestep block read, some atoms contain velocity information, while others do not.
OpenMPCD::MalformedFileException	Throws if the timestep block is malformed or contains fewer atoms than `getNumberOfAtoms()`.

Parameters

[out]	positions	An array capable of holding the positions of holding `3*getNumberOfAtoms()` elements, or `nullptr` if the positions are not desired. If not `nullptr`, the array will be populated in the following format: First, there are the `x`, `y`, and `z` coordinates of atom `0`, in that order; then, the coordinates of atom `1` follow, etc.
[out]	velocities	An array capable of holding the velocities of holding `3*getNumberOfAtoms()` elements, or `nullptr` if the velocities are not desired. If not `nullptr`, the array will be populated in the following format: First, there are the `x`, `y`, and `z` velocities of atom `0`, in that order; then, the coordinates of atom `1` follow, etc. If no velocities are stored in the snapshot file, the given buffer's contents are left unchanged.
[out]	velocitiesEncountered	If not `nullptr`, stores whether the timestep block read contained velocity information.

Returns: Returns true if a complete timestep block has been read.

Definition at line 220 of file VTFSnapshotFile.cpp.

◆ setPrimarySimulationVolumeSize()

void VTFSnapshotFile::setPrimarySimulationVolumeSize	(	const FP &	x,
		const FP &	y,
		const FP &	z
	)

Sets the size of the primary simulation volume.

This information is part of the structure block.

Exceptions

OpenMPCD::InvalidCallException	Throws if the instance is not in write mode.
OpenMPCD::InvalidCallException	Throws if the structure block has already been written.

Parameters

[in]	x	The size along the Cartesian `x` axis.
[in]	y	The size along the Cartesian `y` axis.
[in]	z	The size along the Cartesian `z` axis.

Definition at line 65 of file VTFSnapshotFile.cpp.

◆ structureBlockHasBeenProcessed()

bool OpenMPCD::VTFSnapshotFile::structureBlockHasBeenProcessed ( ) const

inline

Returns whether the structure block has been processed already.

The structure block is read immediately when opening a file in read mode, and written when calling writeTimestepBlock for the first time, or destroying an instance in write mode.

Definition at line 108 of file VTFSnapshotFile.hpp.

◆ writeTimestepBlock()

void VTFSnapshotFile::writeTimestepBlock	(	const FP *const	positions,
		const FP *const	velocities = `NULL`
	)

Starts a new timestep block, and writes the atom coordinates given.

Calling this function will trigger writing of the structure block.

Exceptions

OpenMPCD::InvalidCallException	Throws if the instance is not in write mode.
OpenMPCD::NULLPointerException	Throws if `positions` is `nullptr`.

Parameters

[in]	positions	An array holding the positions of the `getNumberOfAtoms()` atoms, in the following format: First, there are the `x`, `y`, and `z` coordinates of atom `0`, in that order; then, the coordinates of atom `1` follow, etc.
[in]	velocities	An array holding the velocities of the `getNumberOfAtoms()` atoms, in the following format: First, there are the `x`, `y`, and `z` velocities of atom `0`, in that order; then, the velocities of atom `1` follow, etc. If `nullptr` is passed, no velocities are written to the snapshot file.

Definition at line 190 of file VTFSnapshotFile.cpp.

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

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VTFSnapshotFile()

◆ ~VTFSnapshotFile()

Member Function Documentation

◆ declareAtoms() [1/2]

◆ declareAtoms() [2/2]

◆ declareBond()

◆ getAtomProperties()

◆ getBonds()

◆ getNumberOfAtoms()

◆ getPrimarySimulationVolumeSize()

◆ hasBond()

◆ isInReadMode()

◆ isInWriteMode()

◆ isValidAtomID()

◆ primarySimulationVolumeSizeIsSet()

◆ readTimestepBlock()

◆ setPrimarySimulationVolumeSize()

◆ structureBlockHasBeenProcessed()

◆ writeTimestepBlock()