IMP  2.1.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 + 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, 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 kernel::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 SingltonContainer), 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 also 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;
110  void do_before_evaluate();
112  void do_apply(const PairModifier *sm) const;
114 #endif
116 };
117 
119 
120 /** Estimate the proper slack based on
121  - the time taken to evaluate the passed restraints for a given
122  number of particles in the non-bonded list
123  - the number of pairs in the list as a function of slack size
124  - the amount the particles are moved by the optimizer
125  - the time taken to compute the close pairs as a function
126  of slack size
127 
128  For best results, make the particles start in a
129  that is "typical" for the optimization.
130 */
131 IMPCONTAINEREXPORT double get_slack_estimate(
132  const kernel::ParticlesTemp &ps, double upper_bound, double step,
133  const kernel::RestraintsTemp &restraints, bool derivatives, Optimizer *opt,
134  ClosePairContainer *cpc);
135 
136 IMPCONTAINER_END_NAMESPACE
137 
138 #endif /* IMPCONTAINER_CLOSE_PAIR_CONTAINER_H */
virtual ParticleIndexes get_all_possible_indexes() const =0
Get contained particles.
A base class for algorithms to find spatial proximities.
double get_slack_estimate(const kernel::ParticlesTemp &ps, double upper_bound, double step, const kernel::RestraintsTemp &restraints, bool derivatives, Optimizer *opt, ClosePairContainer *cpc)
A shared container for Pairs.
virtual ParticleIndexPairs get_indexes() const =0
Return all close unordered pairs of particles taken from the SingletonContainer.
Import IMP/kernel/Optimizer.h in the namespace.
virtual ParticleIndexPairs get_range_indexes() const =0
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Abstract predicate function.
IMP::base::Vector< IMP::base::Pointer< PairPredicate > > PairPredicates
Base class for all optimizers.
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing sets of objects.
virtual ModelObjectsTemp do_get_inputs() const =0
#define IMP_LIST(protection, Ucname, lcname, Data, PluralData)
A macro to provide a uniform interface for storing lists of objects.
A base class for modifiers of ParticlePairsTemp.