gmx::AnalysisNeighborhoodSearch Class Reference

#include <gromacs/selection/nbsearch.h>

Description

Initialized neighborhood search with a fixed set of reference positions.

An instance of this class is obtained through AnalysisNeighborhood::initSearch(), and can be used to do multiple searches against the provided set of reference positions. It is possible to create concurrent pair searches (including from different threads), as well as call other methods in this class while a pair search is in progress.

This class works like a pointer: copies of it point to the same search. In general, avoid creating copies, and only use the copy/assignment support for moving the variable around. With C++11, this class would best be movable.

Methods in this class do not throw unless otherwise indicated.

Todo:

Make it such that reset() is not necessary to call in code that repeatedly assigns the result of AnalysisNeighborhood::initSearch() to the same variable (see sm_distance.cpp).

Todo:

Consider removing minimumDistance(), as nearestPoint() already returns the distance.

Examples:

template.cpp.

Public Types
typedef std::shared_ptr < internal::AnalysisNeighborhoodSearchImpl >	ImplPointer
	Internal short-hand type for a pointer to the implementation class. More...

Public Member Functions
	AnalysisNeighborhoodSearch ()
	Initializes an invalid search. More...
	AnalysisNeighborhoodSearch (const ImplPointer &impl)
	Internally initialize the search. More...
void	reset ()
	Clears this search. More...
AnalysisNeighborhood::SearchMode	mode () const
	Returns the searching algorithm that this search is using. More...
bool	isWithin (const AnalysisNeighborhoodPositions &positions) const
	Checks whether a point is within a neighborhood. More...
real	minimumDistance (const AnalysisNeighborhoodPositions &positions) const
	Calculates the minimum distance from the reference points. More...
AnalysisNeighborhoodPair	nearestPoint (const AnalysisNeighborhoodPositions &positions) const
	Finds the closest reference point. More...
AnalysisNeighborhoodPairSearch	startSelfPairSearch () const
	Starts a search to find all reference position pairs within a cutoff. More...
AnalysisNeighborhoodPairSearch	startPairSearch (const AnalysisNeighborhoodPositions &positions) const
	Starts a search to find reference positions within a cutoff. More...

Member Typedef Documentation

typedef std::shared_ptr<internal::AnalysisNeighborhoodSearchImpl> gmx::AnalysisNeighborhoodSearch::ImplPointer

Internal short-hand type for a pointer to the implementation class.

shared_ptr is used here to automatically keep a reference count to track whether an implementation class is still used outside the AnalysisNeighborhood object. Ownership currently always stays with AnalysisNeighborhood; it always keeps one instance of the pointer.

Constructor & Destructor Documentation

gmx::AnalysisNeighborhoodSearch::AnalysisNeighborhoodSearch

(

)

Initializes an invalid search.

Such an object cannot be used for searching. It needs to be assigned a value from AnalysisNeighborhood::initSearch() before it can be used. Provided to allow declaring a variable to hold the search before calling AnalysisNeighborhood::initSearch().

gmx::AnalysisNeighborhoodSearch::AnalysisNeighborhoodSearch ( const ImplPointer &  impl )

explicit

Internally initialize the search.

Used to implement AnalysisNeighborhood::initSearch(). Cannot be called from user code.

Member Function Documentation

bool gmx::AnalysisNeighborhoodSearch::isWithin

(

const AnalysisNeighborhoodPositions &

positions

)

const

Checks whether a point is within a neighborhood.

Parameters

[in]

positions

Set of test positions to use.

Returns

true if any of the test positions is within the cutoff of any reference position.

real gmx::AnalysisNeighborhoodSearch::minimumDistance

(

const AnalysisNeighborhoodPositions &

positions

)

const

Calculates the minimum distance from the reference points.

Parameters

[in]

positions

Set of test positions to use.

Returns

The distance to the nearest reference position, or the cutoff value if there are no reference positions within the cutoff.

Examples:

template.cpp.

AnalysisNeighborhood::SearchMode gmx::AnalysisNeighborhoodSearch::mode

(

)

const

Returns the searching algorithm that this search is using.

The return value is never AnalysisNeighborhood::eSearchMode_Automatic.

AnalysisNeighborhoodPair gmx::AnalysisNeighborhoodSearch::nearestPoint

(

const AnalysisNeighborhoodPositions &

positions

)

const

Finds the closest reference point.

Parameters

[in]

positions

Set of test positions to use.

Returns

The reference index identifies the reference position that is closest to the test positions. The test index identifies the test position that is closest to the provided test position. The returned pair is invalid if no reference position is within the cutoff.

void gmx::AnalysisNeighborhoodSearch::reset

(

)

Clears this search.

Equivalent to "*this = AnalysisNeighborhoodSearch();". Currently, this is necessary to avoid unnecessary memory allocation if the previous search variable is still in scope when you want to call AnalysisNeighborhood::initSearch() again.

AnalysisNeighborhoodPairSearch gmx::AnalysisNeighborhoodSearch::startPairSearch

(

const AnalysisNeighborhoodPositions &

positions

)

const

Starts a search to find reference positions within a cutoff.

Parameters

[in]

positions

Set of test positions to use.

Returns

Initialized search object to loop through all reference positions within the configured cutoff.

Exceptions

std::bad_alloc

if out of memory.

If you want to pass the same positions here as you used for the reference positions, consider using startSelfPairSearch(). It can be up to 50% faster.

AnalysisNeighborhoodPairSearch gmx::AnalysisNeighborhoodSearch::startSelfPairSearch

(

)

const

Starts a search to find all reference position pairs within a cutoff.

Returns

Initialized search object to loop through all reference position pairs within the configured cutoff.

Exceptions

std::bad_alloc

if out of memory.

This works as if the reference positions were passed to startPairSearch(), except that it only returns each pair once, instead of returning both i-j and j-i pairs, as startPairSearch() does. i-i pairs are not returned. Note that the order of ref/test indices in the returned pairs is not predictable. That is, one of i-j or j-i is always returned, but there is no control which one.

---

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

• api/legacy/include/gromacs/selection/nbsearch.h
• src/gromacs/selection/nbsearch.cpp