IMP logo
IMP Reference Guide  2.20.0
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-2022 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 
49  //! Return true if this refiner can refine that particle
50  /** This should not throw, so be careful what fields are touched.
51  */
52  virtual bool get_can_refine(Particle *) const { return false; }
53 
54  //! Refine the passed particle into a set of particles.
55  /** As a precondition can_refine_particle(a) should be true.
56 
57  @param a coarse particle to be refined
58  */
59  virtual const ParticlesTemp get_refined(Particle *a) const = 0;
60 
61  //! Return the indexes of the particles returned by get_refined()
62  /** Return the indexes of the particles returned by get_refined()
63  for particle pi in model m.
64 
65  @param m,pi model and particle index of coarse particle to be refined
66 
67  @note assumes that the refined particles are also in model m
68  */
69  virtual ParticleIndexes get_refined_indexes
70  (Model *m, ParticleIndex pi) const;
71 
72  //! Return the indexes of the particles returned by get_refined()
73  /** Return the indexes of the particles returned by get_refined()
74  for particle pi in model m by reference (possibly faster).
75 
76  @param m,pi model and particle index of coarse particle to be refined
77 
78  @note assumes that get_is_by_ref() is true.
79  @note assumes that the refined particles are also in model m
80  */
81  virtual ParticleIndexes const& get_refined_indexes_by_ref
82  (Model *m, ParticleIndex pi) const
83  {
84  IMP_ALWAYS_CHECK(false,
85  "This refiner does not support"
86  " get_refined_indexes_by_ref()",
88  IMP_UNUSED(m);
89  IMP_UNUSED(pi);
90  }
91 
92  //! returns true if this refiner supports
93  //! get_refined_indexes_by_ref() (e.g. FixedRefiner)
94  bool get_is_by_ref_supported() { return is_by_ref_; };
95 
96  //! Get the ith refined particle.
97  /** As a precondition can_refine_particle(a) should be true.
98  */
99  virtual Particle *get_refined(Particle *a, unsigned int i) const {
100  return get_refined(a)[i];
101  }
102 
103  /** As a precondition can_refine_particle(a) should be true.
104  */
105  virtual unsigned int get_number_of_refined(Particle *a) const {
106  return get_refined(a).size();
107  }
108 
109 #ifndef SWIG
110  /** @name Iterating through the set of refined particles
111 
112  Using iterators can be more efficient than using the bulk
113  get_refined(), however it is not necessarily so.
114  @{
115  */
116  typedef internal::IndexingIterator<Accessor> RefinedIterator;
117  RefinedIterator refined_begin(Particle *a) const;
118  RefinedIterator refined_end(Particle *a) const;
119 /** @} */
120 #endif
121 };
122 //! a collection of Refiner objects
124 
125 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
126 struct Refiner::Accessor {
127  // can't reference count since swig memory management is broken
128  Particle *p_;
129  const Refiner *r_;
130  Accessor(Particle *p, const Refiner *r) : p_(p), r_(r) {}
131  Accessor() {}
132  typedef Particle *result_type;
133  Particle *operator()(unsigned int i) const { return r_->get_refined(p_, i); }
134  bool operator==(const Accessor &o) const { return p_ == o.p_ && r_ == o.r_; }
135 };
136 #endif
137 
138 inline Refiner::RefinedIterator Refiner::refined_begin(Particle *a) const {
139  return RefinedIterator(Accessor(a, this), 0);
140 }
141 inline Refiner::RefinedIterator Refiner::refined_end(Particle *a) const {
142  return RefinedIterator(Accessor(a, this), get_number_of_refined(a));
143 }
144 
145 IMPKERNEL_END_NAMESPACE
146 
147 #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:99
Base class for objects that take particle arguments and read from them.
A more IMP-like version of the std::vector.
Definition: Vector.h:42
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
virtual bool get_can_refine(Particle *) const
Return true if this refiner can refine that particle.
Definition: Refiner.h:52
Common base class for heavy weight IMP objects.
Definition: Object.h:111
#define IMP_UNUSED(variable)
Classes used in the construction of ModelObjects.
virtual unsigned int get_number_of_refined(Particle *a) const
Definition: Refiner.h:105
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
Helper macros for throwing and handling exceptions.
Abstract class to implement hierarchical methods.
Definition: Refiner.h:34
Class to handle individual particles of a Model object.
Definition: Particle.h:43
bool get_is_by_ref_supported()
Definition: Refiner.h:94
#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:136