IMP::container::ClosePairContainer Class Reference

Return all close unordered pairs of particles taken from the SingletonContainer. More...

#include <IMP/container/ClosePairContainer.h>

Inheritance diagram for IMP::container::ClosePairContainer:

Detailed Description

Return all close unordered pairs of particles taken from the SingletonContainer.

The ClosePairContainer class maintains a list of particle pairs whose distance (opportunely defined by the decorator, eg., sphere surface distance for XYZR, and center-to-center distance for XYZ) is smaller than the distance_cutoff parameter. It is generally used to construct the non-bonded list for the excluded volume score, as well as electrostatic and van der Waals potential terms.

To increase the efficiency, the stored list actually includes all pairs that are closer than distance_cutoff + 2 * slack. This allows us to reuse the list and only recompute it when a particle moves more than slack. The class keeps track internally of how far the particles have moved using a score state, and is also updated via a score state. A too small a slack value can slow things down because the non-bonded list will be updated frequently. Also, too large a slack value generates many particle pairs whose score is zero, thereby unnecessarily slowing down the score calculation. As a result, it may be useful to experiment with the parameter. You may wish to use the get_slack_estimate() function to help with this experimentation.

Note

The non-bonded list will contain pairs that are further than distance_cutoff apart. If you use an IMP::PairScore with the generated list of pairs, make sure the IMP::PairScore is 0 for distances beyond the distance_cutoff.

As with any invariant in IMP, the contents of the container will only be valid during restraint evaluation, or immediately following a call to kernel::Model::update().

The ClosePairContainer is strongly associated with the SingletonContainerAdaptor provided to it in the constructor. For instance, if the list of particles in the adaptor changes dynamically (by e.g., changing them in the SingletonContainer), the close pair container will also change dynamically.

Here is a simple example of using this for a nonbonded list

## \example container/nonbonded_interactions.py
# This example shows how to set up an excluded volume restraint for a set
# of XYZRDecorator-style particles.

import IMP
import IMP.core
import IMP.atom
import IMP.container

# This example addes a restraint on nonbonded interactions
# after excluding a set of bonded interactions.

m = IMP.kernel.Model()
# The set of particles
ps = IMP.container.ListSingletonContainer(
    IMP.core.create_xyzr_particles(m, 20, 1.0))

# create a bond between two particles
bd0 = IMP.atom.Bonded.setup_particle(ps.get_particle(0))
bd1 = IMP.atom.Bonded.setup_particle(ps.get_particle(1))
IMP.atom.create_custom_bond(bd0, bd1, 2.0)

# Set up the nonbonded list for all pairs at are touching
# and let things move 3 before updating the list
nbl = IMP.container.ClosePairContainer(ps, 0.0, 3.0)
nbl.add_pair_filter(IMP.atom.BondedPairFilter())

# Set up excluded volume
sdps = IMP.core.SoftSpherePairScore(1)
evr = IMP.container.PairsRestraint(sdps, nbl)
m.add_restraint(evr)

# Set up optimizer
o = IMP.core.ConjugateGradients(m)

o.optimize(1000)

See Also

AllPairContainer, CloseBipartitePairContainer, AllBipartitePairContainer for variants on the functionality provided.

Definition at line 66 of file ClosePairContainer.h.

Public Member Functions
	ClosePairContainer (SingletonContainerAdaptor c, double distance_cutoff, double slack=1, std::string name="ClosePairContainer%1%")
	Get the individual particles from the passed SingletonContainer. More...
	ClosePairContainer (SingletonContainerAdaptor c, double distance_cutoff, core::ClosePairsFinder *cpf, double slack=1, std::string name="ClosePairContainer%1%")
	Get the individual particles from the passed SingletonContainer. More...
void	do_apply (const PairModifier *sm) const
kernel::ModelObjectsTemp	do_get_inputs () const
kernel::ParticleIndexes	get_all_possible_indexes () const
	Get contained particles. More...
kernel::ParticleIndexPairs	get_indexes () const
unsigned int	get_number_of_full_rebuilds () const
unsigned int	get_number_of_partial_rebuilds () const
unsigned int	get_number_of_update_calls () const
kernel::ParticleIndexPairs	get_range_indexes () const
double	get_slack () const
virtual std::string	get_type_name () const
virtual ::IMP::base::VersionInfo	get_version_info () const
	Get information about the module and version of the object. More...
void	set_slack (double s)
Public Member Functions inherited from IMP::kernel::PairContainer
void	apply (const PairModifier *sm) const
	Apply a SingletonModifier to the contents. More...
void	apply_generic (const PairModifier *m) const
	Just use apply() in the base class. More...
const kernel::ParticleIndexPairs &	get_contents () const
unsigned int	get_number_of_particle_pairs () const
kernel::ParticlePair	get_particle_pair (unsigned int i) const
kernel::ParticlePairsTemp	get_particle_pairs () const
Public Member Functions inherited from IMP::kernel::Container
ModelObjectsTemp	do_get_outputs () const
	containers don't have outputs More...
std::size_t	get_contents_hash () const
virtual bool	get_is_decomposable () const
Public Member Functions inherited from IMP::kernel::ModelObject
	ModelObject (kernel::Model *m, std::string name)
bool	get_has_dependencies () const
	Return whether this object has dependencies computed. More...
bool	get_has_required_score_states () const
	Return whether score states are computed. More...
ModelObjectsTemp	get_inputs () const
ModelObjectsTemps	get_interactions () const
	Get the interacting sets induced by this ModelObject. More...
Model *	get_model () const
ModelObjectsTemp	get_outputs () const
const ScoreStatesTemp &	get_required_score_states () const
	Get the score states that are ancestors of this in the dependency graph. More...
void	set_has_dependencies (bool tf)
	Either invalidate the dependencies or ensure they are correct. More...
void	set_has_required_score_states (bool tf)
	Compute the required score states. More...
Public Member Functions inherited from IMP::base::Object
virtual void	clear_caches ()
CheckLevel	get_check_level () const
LogLevel	get_log_level () const
void	set_check_level (CheckLevel l)
void	set_log_level (LogLevel l)
	Set the logging level used in this object. More...
void	set_was_used (bool tf) const
void	show (std::ostream &out=std::cout) const
const std::string &	get_name () const
void	set_name (std::string name)

Methods to control the set of filters
PairPredicate objects can be used as filters to prevent the addition of pairs to the container output list. Pairs for which the predicates evaluate to a non-zero value are excluded from the list.
void	remove_pair_filter (PairPredicate *d)
void	remove_pair_filters (const PairPredicates &d)
void	set_pair_filters (const PairPredicates &ps)
void	set_pair_filters_order (const PairPredicates &objs)
unsigned int	add_pair_filter (PairPredicate *obj)
void	add_pair_filters (const PairPredicates &objs)
void	clear_pair_filters ()
unsigned int	get_number_of_pair_filters () const
bool	get_has_pair_filters ()
PairPredicate *	get_pair_filter (unsigned int i) const
PairPredicates	get_pair_filters () const
void	reserve_pair_filters (unsigned int sz)

Additional Inherited Members
Public Types inherited from IMP::kernel::PairContainer
typedef kernel::ParticleIndexPair	ContainedIndexType
typedef kernel::ParticleIndexPairs	ContainedIndexTypes
typedef kernel::ParticlePair	ContainedType
typedef kernel::ParticlePairsTemp	ContainedTypes
typedef PairModifier	Modifier
typedef const kernel::ParticleIndexPair &	PassContainedIndexType
Protected Member Functions inherited from IMP::kernel::PairContainer
	PairContainer (kernel::Model *m, std::string name="PairContainer %1%")
virtual bool	do_get_provides_access () const
Protected Member Functions inherited from IMP::kernel::Container
	Container (kernel::Model *m, std::string name="Container %1%")
Protected Member Functions inherited from IMP::kernel::ModelObject
virtual ModelObjectsTemps	do_get_interactions () const
virtual void	handle_set_has_required_score_states (bool)
Protected Member Functions inherited from IMP::base::Object
	Object (std::string name)
	Construct an object with the given name. More...
virtual void	do_destroy ()

Constructor & Destructor Documentation

IMP::container::ClosePairContainer::ClosePairContainer	(	SingletonContainerAdaptor	c,
		double	distance_cutoff,
		double	slack = 1,
		std::string	name = "ClosePairContainer%1%"
	)

Get the individual particles from the passed SingletonContainer.

Creates a close pair container associated with c.

IMP::container::ClosePairContainer::ClosePairContainer	(	SingletonContainerAdaptor	c,
		double	distance_cutoff,
		core::ClosePairsFinder *	cpf,
		double	slack = 1,
		std::string	name = "ClosePairContainer%1%"
	)

Get the individual particles from the passed SingletonContainer.

Creates a close pair container associated with c. The passed core::ClosePairsFinder is used to generate the list of close pairs, instead of the default.

Member Function Documentation

kernel::ModelObjectsTemp IMP::container::ClosePairContainer::do_get_inputs ( ) const

virtual

Get any Particle, Container or other ModelObjects read by this during evaluation. If you read everything in a container, you can just return that container.

Implements IMP::kernel::ModelObject.

kernel::ParticleIndexes IMP::container::ClosePairContainer::get_all_possible_indexes ( ) const

virtual

Get contained particles.

Get a list of all particles contained in this one, given that the input containers are up to date.

Implements IMP::kernel::Container.

kernel::ParticleIndexPairs IMP::container::ClosePairContainer::get_indexes ( ) const

virtual

Get all the indexes contained in the container.

This should be protected but isn't for compatibility reasons.

External callers should use get_contents().

Implements IMP::kernel::PairContainer.

unsigned int IMP::container::ClosePairContainer::get_number_of_full_rebuilds

(

)

const

Get the number of times this container has computed it contents from scratch.

unsigned int IMP::container::ClosePairContainer::get_number_of_partial_rebuilds

(

)

const

Get the number of times this container has performed a partial recomputation of its contents.

unsigned int IMP::container::ClosePairContainer::get_number_of_update_calls

(

)

const

Get the number of times this container has been asked to update its contents.

kernel::ParticleIndexPairs IMP::container::ClosePairContainer::get_range_indexes ( ) const

virtual

Get all the indexes that might possibly be contained in the container, useful with dynamic containers. For example, with a container::ClosePairContainer, this is the list of all pairs taken from input list (those that are far apart in addition to those that are close).

Implements IMP::kernel::PairContainer.

virtual ::IMP::base::VersionInfo IMP::container::ClosePairContainer::get_version_info ( ) const

virtual

Get information about the module and version of the object.

Reimplemented from IMP::base::Object.

Definition at line 127 of file ClosePairContainer.h.

---

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

• ClosePairContainer.h