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