#include <gromacs/analysisdata/analysisdata.h>

Description

Handle for inserting data into AnalysisData.

This class provides an interface for adding data frames into an AnalysisData object. After a handle is obtained from AnalysisData::startData(), new frames can be added using startFrame(). Then values for that frame are set using provided methods (see below), and finishFrame() is called. After all frames have been added, finishData() (or AnalysisData::finishData()) must be called.

For simple (non-multipoint) data, within a frame values can be set using selectDataSet(), setPoint() and setPoints(). Setting the same column in the same data set multiple times overrides previously set values. When the frame is finished, attached modules are notified.

Multipoint data works otherwise similarly, but requires finishPointSet() to be called for each set of points for which the modules need to be notified. Each point set starts empty (after startFrame() or finishPointSet()), and values can be set using setPoint()/setPoints(). A single point set can contain values only for a single data set, which must be selected with selectDataSet() before setting any values. finishPointSet() must also be called for the last point set just before finishFrame().

This class works like a pointer type: copying and assignment is lightweight, and all copies work interchangeably, accessing the same internal handle. However, normally you should only keep one copy of a handle, i.e., treat this type as movable. Several handles created from the same AnalysisData object can exist concurrently, but must currently operate on separate frames.

Examples:: template.cpp.

Public Member Functions
	AnalysisDataHandle ()
	Constructs an invalid data handle. More...

bool	isValid () const
	Returns whether this data handle is valid.

void	startFrame (int index, real x, real dx=0.0)
	Start data for a new frame. More...

void	selectDataSet (int index)
	Selects a data set for subsequent setPoint()/setPoints() calls. More...

void	setPoint (int column, real value, bool bPresent=true)
	Set a value for a single column for the current frame. More...

void	setPoint (int column, real value, real error, bool bPresent=true)
	Set a value and its error estimate for a single column for the current frame. More...

void	setPoints (int firstColumn, int count, const real *values, bool bPresent=true)
	Set values for consecutive columns for the current frame. More...

void	finishPointSet ()
	Finish data for the current point set. More...

void	finishFrame ()
	Finish data for the current frame. More...

void	finishData ()
	Calls AnalysisData::finishData() for this handle.

Friends
class	AnalysisData
	Needed to access the non-public implementation.

Constructor & Destructor Documentation

gmx::AnalysisDataHandle::AnalysisDataHandle ( )

Constructs an invalid data handle.

This constructor is provided for convenience in cases where it is easiest to declare an AnalysisDataHandle without immediately assigning a value to it. Any attempt to call methods without first assigning a value from AnalysisData::startData() to the handle causes an assert.

Does not throw.

Member Function Documentation

void gmx::AnalysisDataHandle::finishFrame ( )

Finish data for the current frame.

Exceptions

APIError	if any attached data module is not compatible.
unspecified	Any exception thrown by attached data modules in frame notification methods.

Examples:: template.cpp.

void gmx::AnalysisDataHandle::finishPointSet ( )

Finish data for the current point set.

Exceptions

APIError	if any attached data module is not compatible.
unspecified	Any exception thrown by attached data modules in IAnalysisDataModule::pointsAdded().

Must be called after each point set for multipoint data, including the last (i.e., no values must be set between the last call to this method and AnalysisDataStorage::finishFrame()). Must not be called for non-multipoint data.

void gmx::AnalysisDataHandle::selectDataSet ( int index )

Selects a data set for subsequent setPoint()/setPoints() calls.

Parameters

[in] index Zero-based data set index.

After startFrame(), the first data set is always selected. The set value is remembered until the end of the current frame, also across finishPointSet() calls.

Does not throw.

void gmx::AnalysisDataHandle::setPoint	(	int	column,
		real	value,
		bool	bPresent = `true`
	)

Set a value for a single column for the current frame.

Parameters

[in]	column	Zero-based column index.
[in]	value	Value to set for the column.
[in]	bPresent	Present flag to set for the column.

If called multiple times for a column (within one point set for multipoint data), old values are overwritten.

Does not throw.

Examples:: template.cpp.

void gmx::AnalysisDataHandle::setPoint	(	int	column,
		real	value,
		real	error,
		bool	bPresent = `true`
	)

Set a value and its error estimate for a single column for the current frame.

Parameters

[in]	column	Zero-based column index.
[in]	value	Value to set for the column.
[in]	error	Error estimate to set for the column.
[in]	bPresent	Present flag to set for the column.

If called multiple times for a column (within one point set for multipoint data), old values are overwritten.

Does not throw.

void gmx::AnalysisDataHandle::setPoints	(	int	firstColumn,
		int	count,
		const real *	values,
		bool	bPresent = `true`
	)

Set values for consecutive columns for the current frame.

Parameters

[in]	firstColumn	Zero-based column index.
[in]	count	Number of columns to set.
[in]	values	Value array of `column` items.
[in]	bPresent	Present flag to set for the column.

Equivalent to calling setPoint(firstColumn + i, values[i], bPresent) for i from 0 to count.

Does not throw.

void gmx::AnalysisDataHandle::startFrame	(	int	index,
		real	x,
		real	dx = `0.0`
	)

Start data for a new frame.

Parameters

[in]	index	Zero-based index for the frame to start.
[in]	x	x value for the frame.
[in]	dx	Error in x for the frame if applicable.

Exceptions

unspecified Any exception thrown by attached data modules in IAnalysisDataModule::frameStarted().

Each index value 0, 1, ..., N (where N is the total number of frames) should be started exactly once by exactly one handle of an AnalysisData object. The frames may be started out of order, but currently the implementation places some limitations on how far the index can be in the future (as counted from the first frame that is not finished).

Examples:: template.cpp.

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

src/gromacs/analysisdata/analysisdata.h
src/gromacs/analysisdata/analysisdata.cpp

Description

Public Member Functions

Friends

Constructor & Destructor Documentation

Member Function Documentation