IMP logo
IMP Reference Guide  develop.45c11de31d,2024/03/27
The Integrative Modeling Platform
BoundingBox3DSingletonScore.h
Go to the documentation of this file.
1 /**
2  * \file IMP/core/BoundingBox3DSingletonScore.h
3  * \brief Score particles based on a bounding box
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  */
7 
8 #ifndef IMPCORE_BOUNDING_BOX_3DSINGLETON_SCORE_H
9 #define IMPCORE_BOUNDING_BOX_3DSINGLETON_SCORE_H
10 
11 #include <IMP/core/core_config.h>
12 #include <IMP/generic.h>
13 #include <IMP/SingletonScore.h>
14 #include <IMP/singleton_macros.h>
15 #include <IMP/UnaryFunction.h>
17 #include "XYZ.h"
18 #include "internal/evaluate_distance_pair_score.h"
19 #include <boost/lambda/lambda.hpp>
20 
21 IMPCORE_BEGIN_NAMESPACE
22 
23 //! A generic C++ template for scoring particles based on how far outside a
24 //! box they are using unary function UF.
25 /**
26  The bounding box score is evaluated by applying a function f of
27  class UF to a particle based on the distance of its center from
28  the bounding box walls. The radius of the particle is ignored. If
29  the particle is within the bounding box, the score is always
30  0. Logically, it is exepcted that f(0) = 0 and f(x) > 0 if x>0.
31 
32  In Python, use the templated \ref BoundingBox3DSingletonScore class
33  as in the following example. In the example, 10 particles of
34  radius 1.0 are generated in a 10 A x 10 A x 10 A bounding box. The
35  particles are restrained in the bounding box by applying an
36  upper-bounded harmonic potential. It is upper bounded because it
37  is active only outside the bounding box.
38 
39  \code{.py}
40  k_bb = 10.0 # bounding box force coefficient in kcal/mol/A^2
41  bb_side = 10.0 # in A
42  radius = 1.0 # in A
43  number
44  m = IMP.Model()
45  bb = IMP.algebra.BoundingBox3D(IMP.algebra.Vector3D(0, 0, 0),
46  IMP.algebra.Vector3D(bb_side, bb_side, bb_side))
47  particles = []
48  for i in range(0,10):
49  p = IMP.Particle(m)
50  s = IMP.algebra.Sphere3D(
51  IMP.algebra.get_random_vector_in(bb), radius)
52  d = IMP.core.XYZR.setup_particle(p, s)
53  d.set_coordinates_are_optimized(True)
54  particles.append(p)
55  hpb = IMP.core.HarmonicUpperBound(0, k)
56  bbss = IMP.core.BoundingBox3DSingletonScore(hpb, bb)
57  bbr = IMP.container.SingletonsRestraint(bbss, particles)
58  \endcode
59 
60  \see BoundingBox3DSingletonScore
61  \see create_bounding_box_3d_singleton_score
62  */
63 template <class UF>
67 
68  public:
69  /**
70  @param f an unary function applied to particles that are outside the box.
71  f is passed the distance of the particle center from the bounding
72  box walls, ignoring the particle radius. Logically, it is exepcted
73  to satisfy f(0) = 0 and f(x) > 0 if x>0.
74  @param bb the bounding box to which f is applied
75  */
77 
78  /**
79  return 0 if the p is within the bounding box or f(d) if it is
80  outside the bounding box, where f is the unary function provided
81  during construction and d is the distance of the center of p from
82  the bounding box walls.
83  Update derivatives as needed, weighted using da.
84  */
85  virtual double evaluate_index(Model *m, ParticleIndex p,
86  DerivativeAccumulator *da) const override;
88  Model *m, const ParticleIndexes &pis) const override {
89  return IMP::get_particles(m, pis);
90  }
93  ;
94 };
95 
96 #if !defined(SWIG) && !defined(IMP_DOXYGEN)
97 template <class UF>
99  UF *f, const algebra::BoundingBox3D &bb)
100  : f_(f), bb_(bb) {
101  IMP_USAGE_CHECK(std::abs(f_->evaluate(0)) < .1,
102  "The unary function should return "
103  " 0 when passed a value of 0. Not "
104  << f_->evaluate(0));
105 }
106 template <class UF>
108  Model *m, ParticleIndex pi,
109  DerivativeAccumulator *da) const {
111  core::XYZ d(m, pi);
113  bool outside = false;
114  for (unsigned int i = 0; i < 3; ++i) {
115  if (bb_.get_corner(0)[i] > d.get_coordinate(i)) {
116  cp[i] = bb_.get_corner(0)[i];
117  outside = true;
118  } else if (bb_.get_corner(1)[i] < d.get_coordinate(i)) {
119  cp[i] = bb_.get_corner(1)[i];
120  outside = true;
121  } else {
122  cp[i] = d.get_coordinate(i);
123  }
124  }
125  if (outside) {
126  IMP_LOG_VERBOSE("Particle " << Showable(pi) << " is outside box: " << d
127  << " of " << bb_ << std::endl);
128  algebra::Vector3D deriv;
129  double v = internal::compute_distance_pair_score(
130  d.get_coordinates() - cp, f_.get(), &deriv, boost::lambda::_1);
131  if (da) {
132  d.add_to_derivatives(deriv, *da);
133  }
134  return v;
135  } else {
136  return 0;
137  }
138 }
139 
140 #endif
141 
142 //! Score particles based on how far outside a box they are by
143 //! applying f to the distance.
144 //! \see GenericBoundingBox3DSingletonScore
145 /**
146  Example usage is provided in \ref GenericBoundingBox3DSingletonScore
147 */
148 IMP_GENERIC_OBJECT(BoundingBox3DSingletonScore, bounding_box_3d_singleton_score,
149  UnaryFunction,
150  (UnaryFunction *f, const algebra::BoundingBoxD<3> &bb),
151  (f, bb));
152 
153 IMPCORE_END_NAMESPACE
154 
155 #endif /* IMPCORE_BOUNDING_BOX_3DSINGLETON_SCORE_H */
156 
virtual double evaluate_index(Model *m, ParticleIndex p, DerivativeAccumulator *da) const override
#define IMP_OBJECT_METHODS(Name)
Define the basic things needed by any Object.
Definition: object_macros.h:25
#define IMP_OBJECT_LOG
Set the log level to the object's log level.
Definition: log_macros.h:284
Single variable function.
Macros for various classes.
ParticlesTemp get_particles(Model *m, const ParticleIndexes &ps)
Get the particles from a list of indexes.
#define IMP_LOG_VERBOSE(expr)
Definition: log_macros.h:83
A more IMP-like version of the std::vector.
Definition: Vector.h:50
Simple XYZ decorator.
#define IMP_GENERIC_OBJECT(Name, lcname, targument, carguments, cparguments)
Typedefs a default instantiation for a generic (templated) object.
Definition: object_macros.h:60
Class for storing model, its restraints, constraints, and particles.
Definition: Model.h:86
Abstract class for scoring object(s) of type ParticleIndex.
#define IMP_SINGLETON_SCORE_METHODS(Name)
A bounding box in D dimensions.
A decorator for a particle with x,y,z coordinates.
Definition: XYZ.h:30
virtual ModelObjectsTemp do_get_inputs(Model *m, const ParticleIndexes &pis) const override
Overload this method to specify the inputs.
Define SingletonScore.
VectorD< 3 > Vector3D
Definition: VectorD.h:408
GenericBoundingBox3DSingletonScore< UnaryFunction > BoundingBox3DSingletonScore
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
Class for adding derivatives from restraints to the model.
Compile-time generic restraint and constraint support.