IMP logo
IMP Reference Guide  2.7.0
The Integrative Modeling Platform
ClosePairContainer.h
Go to the documentation of this file.
1 /**
2  * \file IMP/container/ClosePairContainer.h
3  * \brief Return all pairs from a SingletonContainer
4  *
5  * Copyright 2007-2017 IMP Inventors. Close rights reserved.
6  */
7 
8 #ifndef IMPCONTAINER_CLOSE_PAIR_CONTAINER_H
9 #define IMPCONTAINER_CLOSE_PAIR_CONTAINER_H
10 
11 #include <IMP/container/container_config.h>
12 #include "internal/ClosePairContainer.h"
13 #include <IMP/Optimizer.h>
14 
15 IMPCONTAINER_BEGIN_NAMESPACE
16 
17 /** \brief Return all close unordered pairs of particles taken from
18  the SingletonContainer
19 
20 The ClosePairContainer class maintains a list of particle pairs whose
21 distance (opportunely defined by the decorator, eg., sphere surface
22 distance for XYZR, and center-to-center distance for XYZ) is smaller
23 than the `distance_cutoff` parameter.
24 It is generally used to construct the non-bonded list for the excluded
25 volume score, as well as electrostatic and van der Waals potential
26 terms.
27 
28 To increase the efficiency, the stored list actually includes all pairs that
29 are closer than `distance_cutoff + 2 * slack`. This allows us to reuse the list
30 and only recompute it when a particle moves more than `slack`.
31 The class keeps track
32 internally of how far the particles have moved using a score state,
33 and is also updated via a score state. A too small a `slack`
34 value can slow things down because the non-bonded list will be updated
35 frequently. Also, too large a slack value generates many particle pairs
36 whose score is zero, thereby unnecessarily slowing down the score
37 calculation. As a result,
38 it may be useful to experiment with the parameter. You may wish to use
39 the get_slack_estimate() function to help with this experimentation.
40 
41 \note The non-bonded list will contain pairs that are further than
42 `distance_cutoff` apart. If you use an IMP::PairScore with the generated
43 list of pairs, make sure the IMP::PairScore is 0 for distances beyond
44 the `distance_cutoff`.
45 
46 \note As with any invariant in \imp, the contents of the container will
47 only be valid during restraint evaluation, or immediately following
48 a call to Model::update().
49 
50 \note The ClosePairContainer is strongly associated with the
51  SingletonContainerAdaptor provided to it in the constructor.
52  For instance, if the list of particles in the adaptor changes dynamically
53  (by e.g., changing them in the SingletonContainer), the close pair
54  container will also change dynamically.
55 
56  Here is a simple example of using this for a nonbonded list
57  \include nonbonded_interactions.py
58 
59  \see AllPairContainer, CloseBipartitePairContainer,
60  AllBipartitePairContainer for variants on the functionality provided.
61 
62  */
63 class IMPCONTAINEREXPORT ClosePairContainer :
64 #if defined(IMP_DOXYGEN) || defined(SWIG)
65  public PairContainer
66 #else
67  public internal::ClosePairContainer
68 #endif
69  {
70  typedef internal::ClosePairContainer P;
71 
72  public:
73  //! Get the individual particles from the passed SingletonContainer
74  /**
75  Creates a close pair container associated with c.
76  */
77  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
78  double slack = 1,
79  std::string name = "ClosePairContainer%1%");
80 
81  //! Get the individual particles from the passed SingletonContainer
82  /**
83  Creates a close pair container associated with c. The passed
84  core::ClosePairsFinder is used to generate the list of close
85  pairs, instead of the default.
86 
87  */
88  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
89  core::ClosePairsFinder *cpf, double slack = 1,
90  std::string name = "ClosePairContainer%1%");
91 
92 #if defined(SWIG) || defined(IMP_DOXYGEN)
93  /** @name Methods to control the set of filters
94 
95  PairPredicate objects can be used as filters to prevent
96  the addition of pairs to the container output list. Pairs
97  for which the predicates evaluate to a non-zero value are
98  excluded from the list.
99  */
100  /**@{*/
101  IMP_LIST(public, PairPredicate, pair_filter, PairPredicate *, PairPredicates);
102  /**@}*/
103  void set_slack(double s);
104  double get_slack() const;
108  void do_apply(const PairModifier *sm) const;
110 
111  /** Get the number of times this container has been asked to update its
112  contents. */
113  unsigned int get_number_of_update_calls() const;
114  /** Get the number of times this container has computed it contents from
115  scratch. */
116  unsigned int get_number_of_full_rebuilds() const;
117  /** Get the number of times this container has performed a partial
118  recomputation of its contents. */
119  unsigned int get_number_of_partial_rebuilds() const;
120 
121  private:
122  virtual std::size_t do_get_contents_hash() const IMP_OVERRIDE;
123 #endif
125 };
126 
128 
129 /** Estimate the proper slack based on
130  - the time taken to evaluate the passed restraints for a given
131  number of particles in the non-bonded list
132  - the number of pairs in the list as a function of slack size
133  - the amount the particles are moved by the optimizer
134  - the time taken to compute the close pairs as a function
135  of slack size
136 
137  For best results, make the particles start in a
138  that is "typical" for the optimization.
139 */
140 IMPCONTAINEREXPORT double get_slack_estimate(
141  const ParticlesTemp &ps, double upper_bound, double step,
142  const RestraintsTemp &restraints, bool derivatives, Optimizer *opt,
143  ClosePairContainer *cpc);
144 
145 IMPCONTAINER_END_NAMESPACE
146 
147 #endif /* IMPCONTAINER_CLOSE_PAIR_CONTAINER_H */
virtual ParticleIndexPairs get_range_indexes() const =0
A shared container for Pairs.
Definition: PairContainer.h:37
A base class for algorithms to find spatial proximities.
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
double get_slack_estimate(const ParticlesTemp &ps, double upper_bound, double step, const RestraintsTemp &restraints, bool derivatives, Optimizer *opt, ClosePairContainer *cpc)
Return all close unordered pairs of particles taken from the SingletonContainer.
Base class for all optimizers.
A more IMP-like version of the std::vector.
Definition: Vector.h:39
A base class for modifiers of ParticlePairsTemp.
Definition: PairModifier.h:32
#define IMP_LIST(protection, Ucname, lcname, Data, PluralData)
A macro to provide a uniform interface for storing lists of objects.
Base class for all optimizers.
Definition: Optimizer.h:46
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
virtual ParticleIndexes get_all_possible_indexes() const =0
Get contained particles.
Abstract predicate function.
Definition: PairPredicate.h:31
virtual ParticleIndexPairs get_indexes() const =0
virtual ModelObjectsTemp do_get_inputs() const =0
#define IMP_OVERRIDE
Cause a compile error if this method does not override a parent method.