IMP logo
IMP Reference Guide  develop.c9d213c767,2020/05/27
The Integrative Modeling Platform
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 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

1 ## \example container/nonbonded_interactions.py
2 # This example shows how to set up an excluded volume restraint for a set
3 # of XYZRDecorator-style particles.
4 
5 import IMP
6 import IMP.core
7 import IMP.atom
8 import IMP.container
9 import sys
10 
11 IMP.setup_from_argv(sys.argv, "nonbonded interactions")
12 
13 # This example addes a restraint on nonbonded interactions
14 # after excluding a set of bonded interactions.
15 
16 m = IMP.Model()
17 # The set of particles
20 
21 # create a bond between two particles
22 bd0 = IMP.atom.Bonded.setup_particle(m, ps.get_indexes()[0])
23 bd1 = IMP.atom.Bonded.setup_particle(m, ps.get_indexes()[1])
24 IMP.atom.create_custom_bond(bd0, bd1, 2.0)
25 
26 # Set up the nonbonded list for all pairs at are touching
27 # and let things move 3 before updating the list
28 nbl = IMP.container.ClosePairContainer(ps, 0.0, 3.0)
29 nbl.add_pair_filter(IMP.atom.BondedPairFilter())
30 
31 # Set up excluded volume
33 evr = IMP.container.PairsRestraint(sdps, nbl)
34 
35 # Set up optimizer
37 o.set_scoring_function([evr])
38 
39 o.optimize(1000)
See Also
AllPairContainer, CloseBipartitePairContainer, AllBipartitePairContainer for variants on the functionality provided.

Definition at line 63 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
 
ModelObjectsTemp do_get_inputs () const
 
ParticleIndexes get_all_possible_indexes () const
 Get contained particles. More...
 
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
 
ParticleIndexPairs get_range_indexes () const
 
double get_slack () const
 
virtual std::string get_type_name () const
 
virtual ::IMP::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::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 ParticleIndexPairsget_contents () const
 
ParticlePair get_particle_pair (unsigned int i) const
 
ParticlePairsTemp get_particle_pairs () const
 
- Public Member Functions inherited from IMP::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::ModelObject
 ModelObject (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...
 
Modelget_model () const
 
ModelObjectsTemp get_outputs () const
 
const ScoreStatesTempget_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::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 added 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 ()
 
PairPredicateget_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::PairContainer
typedef ParticleIndexPair ContainedIndexType
 
typedef ParticleIndexPairs ContainedIndexTypes
 
typedef ParticlePair ContainedType
 
typedef ParticlePairsTemp ContainedTypes
 
typedef PairModifier Modifier
 
typedef const ParticleIndexPairPassContainedIndexType
 
- Protected Member Functions inherited from IMP::PairContainer
 PairContainer (Model *m, std::string name="PairContainer %1%")
 
virtual bool do_get_provides_access () const
 
- Protected Member Functions inherited from IMP::Container
 Container (Model *m, std::string name="Container %1%")
 
- Protected Member Functions inherited from IMP::ModelObject
virtual ModelObjectsTemps do_get_interactions () const
 
virtual void handle_set_has_required_score_states (bool)
 
- Protected Member Functions inherited from IMP::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

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::ModelObject.

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::Container.

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::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.

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::PairContainer.

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

Get information about the module and version of the object.

Reimplemented from IMP::Object.

Definition at line 124 of file ClosePairContainer.h.


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