IMP logo
IMP Reference Guide  develop.29b24c6ad6,2021/05/15
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-2021 IMP Inventors. All 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. 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`. One way to accomplish this is to use a smoothing
45 function (see IMP::atom::SmoothingFunction).
46 
47 \note As with any invariant in \imp, the contents of the container will
48 only be valid during restraint evaluation, or immediately following
49 a call to Model::update().
50 
51 \note The ClosePairContainer is strongly associated with the
52  SingletonContainerAdaptor provided to it in the constructor.
53  For instance, if the list of particles in the adaptor changes dynamically
54  (by e.g., changing them in the SingletonContainer), the close pair
55  container will also change dynamically.
56 
57  Here is a simple example of using this for a nonbonded list
58  \include nonbonded_interactions.py
59 
60  \see AllPairContainer, CloseBipartitePairContainer,
61  AllBipartitePairContainer for variants on the functionality provided.
62 
63  */
64 class IMPCONTAINEREXPORT ClosePairContainer :
65 #if defined(IMP_DOXYGEN) || defined(SWIG)
66  public PairContainer
67 #else
68  public internal::ClosePairContainer
69 #endif
70  {
71  typedef internal::ClosePairContainer P;
72 
73  public:
74  //! Get the individual particles from the passed SingletonContainer
75  /**
76  Creates a close pair container associated with c.
77  */
78  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
79  double slack = 1,
80  std::string name = "ClosePairContainer%1%");
81 
82  //! Get the individual particles from the passed SingletonContainer
83  /**
84  Creates a close pair container associated with c. The passed
85  core::ClosePairsFinder is used to generate the list of close
86  pairs, instead of the default.
87 
88  */
89  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
90  core::ClosePairsFinder *cpf, double slack = 1,
91  std::string name = "ClosePairContainer%1%");
92 
93 #if defined(SWIG) || defined(IMP_DOXYGEN)
94  /** @name Methods to control the set of filters
95 
96  PairPredicate objects can be added as filters to prevent
97  the addition of pairs to the container output list. Pairs
98  for which the predicates evaluate to a non-zero value are
99  excluded from the list.
100  */
101  /**@{*/
102  IMP_LIST(public, PairPredicate, pair_filter, PairPredicate *, PairPredicates);
103  /**@}*/
104  void set_slack(double s);
105  double get_slack() const;
109  void do_apply(const PairModifier *sm) const;
111 
112  /** Get the number of times this container has been asked to update its
113  contents. */
114  unsigned int get_number_of_update_calls() const;
115  /** Get the number of times this container has computed its contents from
116  scratch. */
117  unsigned int get_number_of_full_rebuilds() const;
118  /** Get the number of times this container has performed a partial
119  recomputation of its contents. */
120  unsigned int get_number_of_partial_rebuilds() const;
121 
122  private:
123  virtual std::size_t do_get_contents_hash() const IMP_OVERRIDE;
124 #endif
126 };
127 
129 
130 /** Estimate the proper slack based on
131  - the time taken to evaluate the passed restraints for a given
132  number of particles in the non-bonded list
133  - the number of pairs in the list as a function of slack size
134  - the amount the particles are moved by the optimizer
135  - the time taken to compute the close pairs as a function
136  of slack size
137 
138  For best results, make the particles start in a
139  that is "typical" for the optimization.
140 */
141 IMPCONTAINEREXPORT double get_slack_estimate(
142  const ParticlesTemp &ps, double upper_bound, double step,
143  const RestraintsTemp &restraints, bool derivatives, Optimizer *opt,
144  ClosePairContainer *cpc);
145 
146 IMPCONTAINER_END_NAMESPACE
147 
148 #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:40
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.