IMP logo
IMP Reference Guide  2.19.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-2023 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 #include <cereal/access.hpp>
15 #include <cereal/types/base_class.hpp>
16 
17 IMPCONTAINER_BEGIN_NAMESPACE
18 
19 /** \brief Return all close unordered pairs of particles taken from
20  the SingletonContainer
21 
22 The ClosePairContainer class maintains a list of particle pairs whose
23 distance (opportunely defined by the decorator, eg., sphere surface
24 distance for XYZR, and center-to-center distance for XYZ) is smaller
25 than the `distance_cutoff` parameter.
26 It is generally used to construct the non-bonded list for the excluded
27 volume score, as well as electrostatic and van der Waals potential
28 terms.
29 
30 To increase the efficiency, the stored list actually includes all pairs that
31 are closer than `distance_cutoff + 2 * slack`. This allows us to reuse the list
32 and only recompute it when a particle moves more than `slack`.
33 The class keeps track
34 internally of how far the particles have moved using a score state,
35 and is also updated via a score state. Too small a `slack`
36 value can slow things down because the non-bonded list will be updated
37 frequently. Also, too large a slack value generates many particle pairs
38 whose score is zero, thereby unnecessarily slowing down the score
39 calculation. As a result,
40 it may be useful to experiment with the parameter. You may wish to use
41 the get_slack_estimate() function to help with this experimentation.
42 
43 \note The non-bonded list will contain pairs that are further than
44 `distance_cutoff` apart. If you use an IMP::PairScore with the generated
45 list of pairs, make sure the IMP::PairScore is 0 for distances beyond
46 the `distance_cutoff`. One way to accomplish this is to use a smoothing
47 function (see IMP::atom::SmoothingFunction).
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 internal::ClosePairContainer
71 #endif
72  {
73  typedef internal::ClosePairContainer P;
74 
75  friend class cereal::access;
76 
77  template<class Archive> void serialize(Archive &ar) {
78  ar(cereal::base_class<P>(this));
79  }
80 
82 
83  public:
84  //! Get the individual particles from the passed SingletonContainer
85  /**
86  Creates a close pair container associated with c.
87  */
88  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
89  double slack = 1,
90  std::string name = "ClosePairContainer%1%");
91 
92  //! Get the individual particles from the passed SingletonContainer
93  /**
94  Creates a close pair container associated with c. The passed
95  core::ClosePairsFinder is used to generate the list of close
96  pairs, instead of the default.
97 
98  */
99  ClosePairContainer(SingletonContainerAdaptor c, double distance_cutoff,
100  core::ClosePairsFinder *cpf, double slack = 1,
101  std::string name = "ClosePairContainer%1%");
102 
103  ClosePairContainer() {}
104 
105 #if defined(SWIG) || defined(IMP_DOXYGEN)
106  /** @name Methods to control the set of filters
107 
108  PairPredicate objects can be added as filters to prevent
109  the addition of pairs to the container output list. Pairs
110  for which the predicates evaluate to a non-zero value are
111  excluded from the list.
112  */
113  /**@{*/
115  /**@}*/
116  void set_slack(double s);
117  double get_slack() const;
121  void do_apply(const PairModifier *sm) const;
123 
124  /** Get the number of times this container has been asked to update its
125  contents. */
126  unsigned int get_number_of_update_calls() const;
127  /** Get the number of times this container has computed its contents from
128  scratch. */
129  unsigned int get_number_of_full_rebuilds() const;
130  /** Get the number of times this container has performed a partial
131  recomputation of its contents. */
132  unsigned int get_number_of_partial_rebuilds() const;
133 
134  private:
135  virtual std::size_t do_get_contents_hash() const override;
136 #endif
138 };
139 
141 
142 /** Estimate the proper slack based on
143  - the time taken to evaluate the passed restraints for a given
144  number of particles in the non-bonded list
145  - the number of pairs in the list as a function of slack size
146  - the amount the particles are moved by the optimizer
147  - the time taken to compute the close pairs as a function
148  of slack size
149 
150  For best results, make the particles start in a configuration
151  that is "typical" for the optimization.
152 */
153 IMPCONTAINEREXPORT double get_slack_estimate(
154  Model *m, ParticleIndexes ps, double upper_bound, double step,
155  const RestraintsTemp &restraints, bool derivatives, Optimizer *opt,
156  ClosePairContainer *cpc);
157 
158 IMPCONTAINER_END_NAMESPACE
159 
160 #endif /* IMPCONTAINER_CLOSE_PAIR_CONTAINER_H */
virtual ParticleIndexPairs get_range_indexes() const =0
A shared container for Pairs.
Definition: PairContainer.h:39
double get_slack_estimate(Model *m, ParticleIndexes ps, double upper_bound, double step, const RestraintsTemp &restraints, bool derivatives, Optimizer *opt, ClosePairContainer *cpc)
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
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:42
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.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Base class for all optimizers.
Definition: Optimizer.h:48
#define IMP_OBJECT_SERIALIZE_DECL(Name)
Declare methods needed for serialization of Object pointers.
Definition: object_macros.h:95
#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