Gromacs  2016.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions | Friends
gmx::AnalysisDataHandle Class Reference

#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)
 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
APIErrorif any attached data module is not compatible.
unspecifiedAny 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
APIErrorif any attached data module is not compatible.
unspecifiedAny 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]indexZero-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]columnZero-based column index.
[in]valueValue to set for the column.
[in]bPresentPresent 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]columnZero-based column index.
[in]valueValue to set for the column.
[in]errorError estimate to set for the column.
[in]bPresentPresent 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 
)

Set values for consecutive columns for the current frame.

Parameters
[in]firstColumnZero-based column index.
[in]countNumber of columns to set.
[in]valuesValue array of column items.

Equivalent to calling setPoint(firstColumn + i, values[i]) 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]indexZero-based index for the frame to start.
[in]xx value for the frame.
[in]dxError in x for the frame if applicable.
Exceptions
unspecifiedAny 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: