IMP logo
IMP Reference Guide  develop.e1fe35f,2019/09/16
The Integrative Modeling Platform
Refiner.h
Go to the documentation of this file.
1 /**
2  * \file IMP/Refiner.h
3  * \brief Refine a particle into a list of particles.
4  *
5  * Copyright 2007-2019 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPKERNEL_REFINER_H
9 #define IMPKERNEL_REFINER_H
10 
11 #include <IMP/kernel_config.h>
12 #include "base_types.h"
13 #include "Particle.h"
14 #include "internal/IndexingIterator.h"
15 #include <IMP/deprecation_macros.h>
16 #include <IMP/check_macros.h>
17 #include "model_object_helpers.h"
18 
19 IMPKERNEL_BEGIN_NAMESPACE
20 
21 class Particle;
22 class DerivativeAccumulator;
23 
24 //! Abstract class to implement hierarchical methods.
25 /** The job of this class is to take a single particle and, if
26  appropriate, return a list of particles. These lists can
27  reflect existing relationships, such as the
28  IMP::core::LeavesRefiner, or arbitrary relationships set up
29  for a particular purpose, such as IMP::core::TableRefiner.
30 
31  @note it is assumed that refined particles belong to the same model
32  as the coarse particle
33 */
34 class IMPKERNELEXPORT Refiner : public ParticleInputs, public Object {
35  struct Accessor;
36  bool is_by_ref_;
37 
38  public:
39  /** Constructs the refiner
40 
41  @param name object name for refiner
42  @param is_by_ref if true, this refiner is expected to support
43  the get_refined_indexes_by_ref method,
44  for refiners that support faster cached
45  list of particles, etc.
46  */
47  Refiner(std::string name = "Refiner %1%", bool is_by_ref = false);
48  //! Return true if this refiner can refine that particle
49  /** This should not throw, so be careful what fields are touched.
50  */
51  virtual bool get_can_refine(Particle *) const { return false; }
52 
53  //! Refine the passed particle into a set of particles.
54  /** As a precondition can_refine_particle(a) should be true.
55 
56  @param a coarse particle to be refined
57  */
58  virtual const ParticlesTemp get_refined(Particle *a) const = 0;
59 
60  //! Return the indexes of the particles returned by get_refined()
61  /** Return the indexes of the particles returned by get_refined()
62  for particle pi in model m.
63 
64  @param m,pi model and particle index of coarse particle to be refined
65 
66  @note assumes that the refined particles are also in model m
67  */
68  virtual ParticleIndexes get_refined_indexes
69  (Model *m, ParticleIndex pi) const;
70 
71  //! Return the indexes of the particles returned by get_refined()
72  /** Return the indexes of the particles returned by get_refined()
73  for particle pi in model m by reference (possibly faster).
74 
75  @param m,pi model and particle index of coarse particle to be refined
76 
77  @note assumes that get_is_by_ref() is true.
78  @note assumes that the refined particles are also in model m
79  */
80  virtual ParticleIndexes const& get_refined_indexes_by_ref
81  (Model *m, ParticleIndex pi) const
82  {
83  IMP_ALWAYS_CHECK(false,
84  "This refiner does not support"
85  " get_refined_indexes_by_ref()",
87  IMP_UNUSED(m);
88  IMP_UNUSED(pi);
89  }
90 
91  //! returns true if this refiner supports
92  //! get_refined_indexes_by_ref() (e.g. FixedRefiner)
93  bool get_is_by_ref_supported() { return is_by_ref_; };
94 
95  //! Get the ith refined particle.
96  /** As a precondition can_refine_particle(a) should be true.
97  */
98  virtual Particle *get_refined(Particle *a, unsigned int i) const {
99  return get_refined(a)[i];
100  }
101 
102  /** As a precondition can_refine_particle(a) should be true.
103  */
104  virtual unsigned int get_number_of_refined(Particle *a) const {
105  return get_refined(a).size();
106  }
107 
108 #ifndef SWIG
109  /** @name Iterating through the set of refined particles
110 
111  Using iterators can be more efficient than using the bulk
112  get_refined(), however it is not necessarily so.
113  @{
114  */
115  typedef internal::IndexingIterator<Accessor> RefinedIterator;
116  RefinedIterator refined_begin(Particle *a) const;
117  RefinedIterator refined_end(Particle *a) const;
118 /** @} */
119 #endif
120 };
121 //! a collection of Refiner objects
123 
124 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
125 struct Refiner::Accessor {
126  // can't reference count since swig memory management is broken
127  Particle *p_;
128  const Refiner *r_;
129  Accessor(Particle *p, const Refiner *r) : p_(p), r_(r) {}
130  Accessor() {}
131  typedef Particle *result_type;
132  Particle *operator()(unsigned int i) const { return r_->get_refined(p_, i); }
133  bool operator==(const Accessor &o) const { return p_ == o.p_ && r_ == o.r_; }
134 };
135 #endif
136 
137 inline Refiner::RefinedIterator Refiner::refined_begin(Particle *a) const {
138  return RefinedIterator(Accessor(a, this), 0);
139 }
140 inline Refiner::RefinedIterator Refiner::refined_end(Particle *a) const {
141  return RefinedIterator(Accessor(a, this), get_number_of_refined(a));
142 }
143 
144 IMPKERNEL_END_NAMESPACE
145 
146 #endif /* IMPKERNEL_REFINER_H */
Control display of deprecation information.
Basic types used by IMP.
virtual Particle * get_refined(Particle *a, unsigned int i) const
Get the ith refined particle.
Definition: Refiner.h:98
Base class for objects that take particle arguments and read from them.
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:72
virtual bool get_can_refine(Particle *) const
Return true if this refiner can refine that particle.
Definition: Refiner.h:51
Common base class for heavy weight IMP objects.
Definition: Object.h:106
#define IMP_UNUSED(variable)
Classes used in the construction of ModelObjects.
virtual unsigned int get_number_of_refined(Particle *a) const
Definition: Refiner.h:104
Classes to handle individual model particles. (Note that implementation of inline functions is in int...
#define IMP_OBJECTS(Name, PluralName)
Define the types for storing lists of object pointers.
Definition: object_macros.h:44
Exception definitions and assertions.
Abstract class to implement hierarchical methods.
Definition: Refiner.h:34
Class to handle individual particles of a Model object.
Definition: Particle.h:41
bool get_is_by_ref_supported()
Definition: Refiner.h:93
#define IMP_ALWAYS_CHECK(condition, message, exception_name)
Throw an exception if a check fails.
Definition: check_macros.h:61
An exception for an invalid value being passed to IMP.
Definition: exception.h:137