IMP  2.0.1
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  * This file is generated by a script (core/tools/make-container).
6  * Do not edit directly.
7  *
8  * Copyright 2007-2013 IMP Inventors. Close rights reserved.
9  */
10 
11 #ifndef IMPCONTAINER_CLOSE_PAIR_CONTAINER_H
12 #define IMPCONTAINER_CLOSE_PAIR_CONTAINER_H
13 
14 #include <IMP/container/container_config.h>
15 #include <IMP/core/internal/CoreClosePairContainer.h>
16 #include <IMP/Optimizer.h>
17 
18 IMPCONTAINER_BEGIN_NAMESPACE
19 
20 /** \brief Return all close unordered pairs of particles taken from
21  the SingletonContainer
22 
23 The ClosePairContainer class maintains a list of particle pairs whose
24 distance (opportunely defined by the decorator, eg., sphere surface
25 distance for XYZR, and center-to-center distance for XYZ) is smaller
26 than the `distance_cutoff` parameter.
27 It is generally used to construct the non-bonded list for the excluded
28 volume score, as well as electrostatic and van der Waals potential
29 terms.
30 
31 To increase the efficiency, the stored list actually includes all pairs that
32 are closer than `distance_cutoff + slack`. This allows us to reuse the list
33 and only recompute it when a particle moves more than `slack`.
34 The class keeps track
35 internally of how far the particles have moved using a score state,
36 and is also updated via a score state. A too small a `slack`
37 value can slow things down because the non-bonded list will be updated
38 frequently. Also, a too large a slack value generates many particle pairs
39 whose score is zero, thereby unnecessarily slowing down the score
40 calculation. As a result,
41 it may be useful to experiment with the parameter. You may wish to use
42 the get_slack_estimate() function to help with this experimentation.
43 
44 \note The non-bonded list will contain pairs that are further than
45 `distance_cutoff` apart. If you use an IMP::PairScore with the generated
46 list of pairs, make sure the IMP::PairScore is 0 for distances beyond
47 the `distance_cutoff`.
48 
49 \note As with any invariant in \imp, the contents of the container will
50 only be value during restraint evaluation, or immediately following
51 a call to Model::update().
52 
53  Here is a simple example of using this for a nonbonded list
54  \verbinclude nonbonded_interactions.py
55 
56  \see CloseBipartitePairContainer
57  \see core::ClosePairsFinder
58 
59  */
60 class IMPCONTAINEREXPORT ClosePairContainer :
61 #if defined(IMP_DOXYGEN) || defined(SWIG)
62 public PairContainer
63 #else
64 public core::internal::CoreClosePairContainer
65 #endif
66 {
67  typedef core::internal::CoreClosePairContainer P;
68 public:
69  //! Get the individual particles from the passed SingletonContainer
70  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
71  double slack=1);
72 
73  //! Get the individual particles from the passed SingletonContainer
74  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
76  double slack=1);
77 
78 #if defined(SWIG) || defined(IMP_DOXYGEN)
79  /** @name Methods to control the set of filters
80 
81  PairPredicate objects can be used as filters to prevent
82  the addition of pairs to the container output list. Pairs
83  for which the predicates evaluate to a non-zero value are
84  excluded from the list.
85  */
86  /**@{*/
87  IMP_LIST(public, PairPredicate, pair_filter,
89  /**@}*/
90  void set_slack(double s);
91  double get_slack() const;
93 #else
95 #endif
96 };
97 
99 
100 
101 /** Estimate the proper slack based on
102  - the time taken to evaluate the passed restraints for a given
103  number of particles in the non-bonded list
104  - the number of pairs in the list as a function of slack size
105  - the amount the particles are moved by the optimizer
106  - the time taken to compute the close pairs as a function
107  of slack size
108 
109  For best results, make the particles start in a
110  that is "typical" for the optimization.
111 */
112 IMPCONTAINEREXPORT double
113 get_slack_estimate(const ParticlesTemp& ps,
114  double upper_bound,
115  double step,
116  const RestraintsTemp &restraints,
117  bool derivatives,
118  Optimizer *opt,
119  ClosePairContainer *cpc);
120 
121 
122 IMPCONTAINER_END_NAMESPACE
123 
124 #endif /* IMPCONTAINER_CLOSE_PAIR_CONTAINER_H */