IMP logo
IMP Reference Guide  2.20.1
The Integrative Modeling Platform
vector_generators.h
Go to the documentation of this file.
1 /**
2  * \file IMP/algebra/vector_generators.h
3  * \brief Functions to generate vectors.
4  *
5  * Copyright 2007-2022 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPALGEBRA_VECTOR_GENERATORS_H
10 #define IMPALGEBRA_VECTOR_GENERATORS_H
11 
12 #include "VectorD.h"
13 #include "Cylinder3D.h"
14 #include "Cone3D.h"
15 #include "Sphere3D.h"
16 #include "SpherePatch3D.h"
17 #include "BoundingBoxD.h"
18 #include "utility.h"
19 #include "internal/grid_range_d.h"
20 #include "internal/internal_vector_generators.h"
21 
22 IMPALGEBRA_BEGIN_NAMESPACE
23 
24 /** @name Vector Generators
25 
26  These functions generate vector objects. Some
27  of the methods, those with random in their name, generate
28  a single vector chosen uniformly from the specified domain.
29  Others, the cover methods, generate a set of points distributed
30  (somewhat) evenly over the domain.
31  @{
32  */
33 
34 //! Generate a random vector in a box with uniform density
35 /** \see BoundingBoxD
36  \see VectorD
37  */
38 template <int D>
41 }
42 
43 //! Generate a random vector on a box with uniform density
44 /** \see BoundingBoxD
45  \see VectorD
46  */
47 template <int D>
49  return internal::RandomVectorOnBB<D>::get(bb);
50 }
51 
52 //! Generate a random vector in a sphere with uniform density
53 /** \see VectorD
54  \see SphereD
55  */
56 template <int D>
58  IMP_USAGE_CHECK(s.get_radius() > 0, "The sphere must have positive radius");
60  double norm;
61  VectorD<D> ret;
62  double r2 = get_squared(s.get_radius());
63  // \todo This algorithm could be more efficient.
64  do {
65  ret = get_random_vector_in(bb);
66  norm = (s.get_center() - ret).get_squared_magnitude();
67  } while (norm > r2);
68  return ret;
69 }
70 
71 #ifndef SWIG
72 /** Generates a random vector in a circle
73  with uniform density with respect to the area of the circle
74 
75  @param s a 2D sphere (circle)
76 
77  \see VectorD
78  \see SphereD
79 */
80 IMPALGEBRAEXPORT VectorD<2> get_random_vector_in(const SphereD<2> &s);
81 #endif
82 
83 //! Generate a random vector in a cylinder with uniform density
84 /** \see VectorD
85  \see Cylinder3D
86  */
87 IMPALGEBRAEXPORT Vector3D get_random_vector_in(const Cylinder3D &c);
88 
89 //! returns a random vector on a sphere of radius 1 with uniform density
90 //! and implementation optimized for the 3D + unit vector case
93 }
94 
95 //! Generate a random vector on a sphere with uniform density
96 /** \see VectorD
97  \see SphereD
98  */
99 template <int D>
102 }
103 
104 //! Generate a set of vectors which covers a sphere uniformly
105 /** The function is currently pretty slow, especially in non-optimized
106  builds. Complain if this bugs you. We might be able to do better,
107  at least in 3D.
108 
109  Creates at least the requested number of points.
110  \cgalpredicate
111 
112  \see VectorD
113  \see SphereD
114  */
115 template <int D>
117  unsigned int n) {
118  return internal::uniform_cover_sphere(n, s.get_center(), s.get_radius(),
119  true);
120 }
121 
122 //! Generate a set of 3d points that uniformly cover a cylinder
123 /** \see VectorD
124  \see Cylinder3D
125 */
126 IMPALGEBRAEXPORT Vector3Ds
127  get_uniform_surface_cover(const Cylinder3D &cyl, int number_of_points);
128 
129 //! Generate a set of 3D points that uniformly cover a hemisphere
130 /** The points all lie on the upper hemisphere, eg, all their
131  z coordinates are greater than those of the center of the sphere.
132  */
133 template <int D>
135  const SphereD<D> &s, unsigned int n) {
136  return internal::uniform_cover_sphere(n, s.get_center(), s.get_radius(),
137  false);
138 }
139 
140 //! Generate a random vector on a unit simplex with uniform density
141 /** \see VectorD
142  \see UnitSimplexD
143  */
144 template <int D>
147 }
148 
149 //! Generate a grid of 3d points on a cylinder surface
150 /** \see Vector3D
151  \see Cylinder3D
152 */
153 IMPALGEBRAEXPORT Vector3Ds
154  get_grid_surface_cover(const Cylinder3D &cyl, int number_of_cycles,
155  int number_of_points_on_cycle);
156 
157 //! Generate a set of 3d points that uniformly cover a patch of a sphere
158 /**
159  \note the implementation can be improved
160  \see SpherePatch3D
161  \see VectorD
162  */
163 IMPALGEBRAEXPORT Vector3Ds
164  get_uniform_surface_cover(const SpherePatch3D &sph,
165  unsigned int number_of_points);
166 
167 /** \see VectorD
168  \see Cone3D
169 */
170 IMPALGEBRAEXPORT Vector3Ds
171  get_uniform_surface_cover(const Cone3D &cone,
172  unsigned int number_of_points);
173 
174 /** Cover the interior of the bounding box by equal sized
175  parallelograms of approximately full-width s, returning the
176  list of centers of the cubes.
177  */
178 template <int D>
180  const BoundingBoxD<D> &bb, double s) {
181  const unsigned int dim = bb.get_dimension();
182  Ints ns(dim);
183  algebra::VectorD<D> start(bb.get_corner(0));
184  algebra::VectorD<D> spacing(bb.get_corner(0));
185  for (unsigned int i = 0; i < dim; ++i) {
186  double w = bb.get_corner(1)[i] - bb.get_corner(0)[i];
187  if (w < s) {
188  start[i] = bb.get_corner(0)[i] + w * .5;
189  spacing[i] = 1;
190  ns[i] = 1;
191  } else {
192  ns[i] = static_cast<int>(std::floor(w / s));
193  spacing[i] = w / ns[i];
194  start[i] = bb.get_corner(0)[i] + spacing[i] * .5;
195  }
196  }
197  Ints cur(D, 0);
198  Vector<VectorD<D> > ret;
199  do {
200  ret.push_back(start + get_elementwise_product(cur, spacing));
201  unsigned int i;
202  for (i = 0; i < dim; ++i) {
203  ++cur[i];
204  if (cur[i] == ns[i]) {
205  cur[i] = 0;
206  } else {
207  break;
208  }
209  }
210  if (i == dim) break;
211  } while (true);
212  return ret;
213 }
214 
215 //! Generate a random chain with no collisions
216 /** This function generates a random chain, starting at (0,0,0)
217  with n particles each with radius r. Consecutive particles are
218  approximately distance 2r apart and no pair of particles is closer
219  than 2r.
220 
221  If an obstacles parameter is provided then chain spheres also don't
222  intersect the obstacle spheres.
223 
224  \note The current implementation is not very clever and can be made
225  more clever if needed.
226  */
227 IMPALGEBRAEXPORT Vector3Ds
228  get_random_chain(unsigned int n, double r,
229  const Vector3D &start = Vector3D(0, 0, 0),
230  const Sphere3Ds &obstacles = Sphere3Ds());
231 
232 /** @} */
233 
234 /** Return a cover of the surface of the volume defined by a union of balls
235  bounded by the spheres.
236 
237  This is effectively a sampling of the solvent exposed surface of a set of
238  spheres. The density of points has approximately the passed value.
239 
240  This method is much faster than get_connolly_surface().
241 */
242 IMPALGEBRAEXPORT Vector3Ds
244  double points_per_square_angstrom);
245 IMPALGEBRA_END_NAMESPACE
246 
247 #endif /* IMPALGEBRA_VECTOR_GENERATORS_H */
Simple 3D sphere patch class.
VectorD< D > get_elementwise_product(const algebra::VectorD< D > &a, const algebra::VectorD< D > &b)
Return the vector that is the elementwise product of the two.
Definition: VectorD.h:461
const VectorD< D > & get_corner(unsigned int i) const
For 0 return lower corner and for 1, the upper corner.
Definition: BoundingBoxD.h:140
VectorD< 3 > get_random_vector_on_unit_sphere()
Represent a cylinder in 3D.
Vector3Ds get_random_chain(unsigned int n, double r, const Vector3D &start=Vector3D(0, 0, 0), const Sphere3Ds &obstacles=Sphere3Ds())
Generate a random chain with no collisions.
Vector< VectorD< 3 > > Vector3Ds
Definition: VectorD.h:427
Represent a unit simplex embedded in D-dimensional real space.
Definition: UnitSimplexD.h:70
A more IMP-like version of the std::vector.
Definition: Vector.h:42
Vector3D get_random_vector_in(const Cylinder3D &c)
Generate a random vector in a cylinder with uniform density.
Functions to deal with very common math operations.
A Cartesian vector in D-dimensions.
Definition: VectorD.h:56
BoundingBoxD< 3 > get_bounding_box(const Cone3D &g)
Definition: Cone3D.h:71
A bounding box in D dimensions.
Simple D vector class.
IMP::Vector< Sphere3D > Sphere3Ds
Definition: SphereD.h:104
An axis-aligned bounding box.
Definition: BoundingBoxD.h:28
Vector3Ds get_uniform_surface_cover(const Sphere3Ds &in, double points_per_square_angstrom)
Represent a cone in 3D.
VectorD< 3 > Vector3D
Definition: VectorD.h:425
#define IMP_USAGE_CHECK(expr, message)
A runtime test for incorrect usage of a class or method.
Definition: check_macros.h:168
VectorD< D > get_random_vector_on(const UnitSimplexD< D > &s)
Generate a random vector on a unit simplex with uniform density.
Vector< VectorD< D > > get_grid_interior_cover_by_spacing(const BoundingBoxD< D > &bb, double s)
Simple 3D sphere class.
Vector< VectorD< D > > get_uniform_upper_hemisphere_cover(const SphereD< D > &s, unsigned int n)
Generate a set of 3D points that uniformly cover a hemisphere.
Vector3Ds get_grid_surface_cover(const Cylinder3D &cyl, int number_of_cycles, int number_of_points_on_cycle)
Generate a grid of 3d points on a cylinder surface.
Represent a sphere in D-dimensions.
Definition: SphereD.h:26