2 Highly Optimized Object-oriented Many-particle Dynamics -- Blue Edition
3 (HOOMD-blue) Open Source Software License Copyright 2009-2014 The Regents of
4 the University of Michigan All rights reserved.
6 HOOMD-blue may contain modifications ("Contributions") provided, and to which
7 copyright is held, by various Contributors who have granted The Regents of the
8 University of Michigan the right to modify and/or distribute such Contributions.
10 You may redistribute, use, and create derivate works of HOOMD-blue, in source
11 and binary forms, provided you abide by the following conditions:
13 * Redistributions of source code must retain the above copyright notice, this
14 list of conditions, and the following disclaimer both in the code and
15 prominently in any materials provided with the distribution.
17 * Redistributions in binary form must reproduce the above copyright notice, this
18 list of conditions, and the following disclaimer in the documentation and/or
19 other materials provided with the distribution.
21 * All publications and presentations based on HOOMD-blue, including any reports
22 or published results obtained, in whole or in part, with HOOMD-blue, will
23 acknowledge its use according to the terms posted at the time of submission on:
24 http://codeblue.umich.edu/hoomd-blue/citations.html
26 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
27 http://codeblue.umich.edu/hoomd-blue/
29 * Apart from the above required attributions, neither the name of the copyright
30 holder nor the names of HOOMD-blue's contributors may be used to endorse or
31 promote products derived from this software without specific prior written
36 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS IS'' AND
37 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
38 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND/OR ANY
39 WARRANTIES THAT THIS SOFTWARE IS FREE OF INFRINGEMENT ARE DISCLAIMED.
41 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
42 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
43 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
44 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
45 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
46 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
47 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
50 // Maintainer: joaander
52 #include <boost/shared_ptr.hpp>
53 #include <boost/signals2.hpp>
61 \brief Declares the CellList class
65 #error This header cannot be compiled by nvcc
68 #ifndef __CELLLIST_H__
69 #define __CELLLIST_H__
71 //! Computes a cell list from the particles in the system
73 Cell lists are useful data structures when working with locality queries on particles. The most notable useage of
74 cell lists in HOOMD is as an auxilliary data structure used when building the neighbor list. The data layout design
75 decisions for CellList were made to optimize the performance of the neighbor list build as deteremined by
76 microbenchmarking. However, CellList is written as generally as possible so that it can be used throughout the code
77 in other locations where a cell list is needed.
79 A cell list defines a set of cuboid cells that completely covers the simulation box. A single nominal width is given
80 which is then rounded up to fit an integral number of cells across each dimension. A given particle belongs in one
81 and only one cell, the one that contains the particle's x,y,z position.
85 All data is stored in GPUArrays for access on the host and device.
87 - The \c cell_size array lists the number of members in each cell.
88 - The \c xyzf array contains Scalar4 elements each of which holds the x,y,z coordinates of the particle and a flag.
89 That flag can optionally be the particle index, its charge, or its type.
90 - The \c tdb array contains Scalar4 elements each of which holds the type, diameter, and body of the particle.
91 It is only computed is requested to reduce the computation time when it is not needed.
92 - The \c orientation array contains Scalar4 elements listing the orientation of each particle.
93 It is only computed is requested to reduce the computation time when it is not needed.
94 - The \c idx array contains unsigned int elements listing the index of each particle. It is useful when xyzf is
95 set to hold type. It is only computed is requested to reduce the computation time when it is not needed.
96 - The cell_adj array lists indices of adjacent cells. A specified radius (3,5,7,...) of cells is included in the
99 A given cell cuboid with x,y,z indices of i,j,k has a unique cell index. This index can be obtained from the Index3D
100 object returned by getCellIndexer()
102 Index3D cell_indexer = cl->getCellIndexer();
103 cidx = cell_indexer(i,j,k);
106 The other arrays are 2D (or 4D if you include i,j,k) in nature. They can be indexed with the appropriate Index2D
107 from getCellListIndexer() or getCellAdjIndexer().
109 Index2D cell_list_indexer = cl->getCellListIndexer();
110 Index2D cell_adj_indexer = cl->getCellAdjIndexer();
113 - <code>cell_size[cidx]</code> is the number of particles in the cell with index \c cidx
114 - \c xyzf is Ncells x Nmax and <code>xyzf[cell_list_indexer(offset,cidx)]</code> is the data stored for particle
115 \c offset in cell \c cidx (\c offset can vary from 0 to <code>cell_size[cidx]-1</code>)
116 - \c tbd, idx, and orientation is structured identically to \c xyzf
117 - <code>cell_adj[cell_adj_indexer(offset,cidx)]</code> is the cell index for neighboring cell \c offset to \c cidx.
118 \c offset can vary from 0 to (radius*2+1)^3-1 (typically 26 with radius 1)
121 - \c width - minimum width of a cell in any x,y,z direction
122 - \c radius - integer radius of cells to generate in \c cell_adj (1,2,3,4,...)
123 - \c max_cells - maximum number of cells to allocate
124 - \c multiple - Round down to the nearest multiple number of cells in each direction (only applied to cells
125 inside the domain, not the ghost cells).
127 After a set call is made to adjust a parameter, changes do not take effect until the next call to compute().
129 <b>Overvlow and error flag handling:</b>
130 For easy support of derived GPU classes to implement overvlow detection and error handling, all error flags are
131 stored in the GPUArray \a d_conditions.
132 - 0: Maximum cell size (implementations are free to write to this element only in overflow conditions if they
134 - 1: Set to non-zero if any particle has nan coordinates
135 - 2: Set to non-zero if any particle is outside of the addressable bins
137 Condition flags are to be set during the computeCellList() call and will be checked by compute() which will then
138 take the appropriate action. If possible, flags 1 and 2 should be set to the index of the particle causing the
141 class CellList
: public Compute
144 //! Construct a cell list
145 CellList(boost::shared_ptr
<SystemDefinition
> sysdef
);
149 //! \name Set parameters
152 //! Set the minimum cell width in any dimension
153 void setNominalWidth(Scalar width
)
155 m_nominal_width
= width
;
156 m_params_changed
= true;
159 //! Set the radius of cells to include in the adjacency list
160 void setRadius(unsigned int radius
)
163 m_params_changed
= true;
166 //! Set the maximum number of cells to allocate
167 void setMaxCells(unsigned int max_cells
)
169 m_max_cells
= max_cells
;
170 m_params_changed
= true;
173 //! Specify if the TDB cell list is to be computed
174 void setComputeTDB(bool compute_tdb
)
176 m_compute_tdb
= compute_tdb
;
177 m_params_changed
= true;
180 //! Specify if the orientation cell list is to be computed
181 void setComputeOrientation(bool compute_orientation
)
183 m_compute_orientation
= compute_orientation
;
184 m_params_changed
= true;
187 //! Specify if the index cell list is to be computed
188 void setComputeIdx(bool compute_idx
)
190 m_compute_idx
= compute_idx
;
191 m_params_changed
= true;
194 //! Specify that the flag is to be filled with the particle charge
197 m_flag_charge
= true;
199 m_params_changed
= true;
202 //! Specify that the flag is to be filled with the particle type
205 m_flag_charge
= false;
207 m_params_changed
= true;
210 //! Specify that the flag is to be the particle index (encoded as an integer in the Scalar variable)
213 m_flag_charge
= false;
215 m_params_changed
= true;
218 //! Notification of a particle resort
219 void slotParticlesSorted()
221 m_particles_sorted
= true;
224 //! Notification of a box size change
225 void slotBoxChanged()
227 m_box_changed
= true;
228 m_force_compute
= true;
231 //! Set the multiple value
232 void setMultiple(unsigned int multiple
)
235 m_multiple
= multiple
;
241 //! \name Get properties
244 //! Get the nominal width of the cells
245 Scalar
getNominalWidth() const
247 return m_nominal_width
;
250 //! Get the dimensions of the cell list
251 const uint3
& getDim() const
256 //! Get an indexer to identify cell indices
257 const Index3D
& getCellIndexer() const
259 return m_cell_indexer
;
262 //! Get an indexer to index into the cell lists
263 const Index2D
& getCellListIndexer() const
265 return m_cell_list_indexer
;
268 //! Get an indexer to index into the adjacency list
269 const Index2D
& getCellAdjIndexer() const
271 return m_cell_adj_indexer
;
274 //! Get number of memory slots allocated for each cell
275 const unsigned int getNmax() const
280 //! Get number of ghost cells per direction
281 const uint3
getNGhostCells() const
283 return m_num_ghost_cells
;
286 //! Get width of ghost cells
287 const Scalar3
getGhostWidth() const
289 return m_ghost_width
;
296 //! Get the array of cell sizes
297 const GPUArray
<unsigned int>& getCellSizeArray() const
302 //! Get the adjacency list
303 const GPUArray
<unsigned int>& getCellAdjArray() const
308 //! Get the cell list containing x,y,z,flag
309 const GPUArray
<Scalar4
>& getXYZFArray() const
314 //! Get the cell list containting t,d,b
315 const GPUArray
<Scalar4
>& getTDBArray() const
320 //! Get the cell list containing orientation
321 const GPUArray
<Scalar4
>& getOrientationArray() const
323 return m_orientation
;
326 //! Get the cell list containing index
327 const GPUArray
<unsigned int>& getIndexArray() const
333 //! Compute the cell list given the current particle positions
334 void compute(unsigned int timestep
);
336 //! Benchmark the computation
337 double benchmark(unsigned int num_iters
);
339 //! Print statistics on the cell list
340 virtual void printStats();
345 // user specified parameters
346 Scalar m_nominal_width
; //!< Minimum width of cell in any direction
347 unsigned int m_radius
; //!< Radius of adjacency bins to list
348 unsigned int m_max_cells
; //!< Maximum number of cells to allocate
349 bool m_compute_tdb
; //!< true if the tdb list should be computed
350 bool m_compute_orientation
; //!< true if the orientation list should be computed
351 bool m_compute_idx
; //!< true if the idx list should be computed
352 bool m_flag_charge
; //!< true if the flag should be set to the charge, it will be index (or type) otherwise
353 bool m_flag_type
; //!< true if the flag should be set to type, it will be index otherwise
354 bool m_params_changed
; //!< Set to true when parameters are changed
355 bool m_particles_sorted
; //!< Set to true when the particles have been sorted
356 bool m_box_changed
; //!< Set to ttrue when the box size has changed
357 unsigned int m_multiple
; //!< Round cell dimensions down to a multiple of this value
359 // parameters determined by initialize
360 uint3 m_dim
; //!< Current dimensions
361 Index3D m_cell_indexer
; //!< Indexes cells from i,j,k
362 Index2D m_cell_list_indexer
; //!< Indexes elements in the cell list
363 Index2D m_cell_adj_indexer
; //!< Indexes elements in the cell adjacency list
364 unsigned int m_Nmax
; //!< Numer of spaces reserved for particles in each cell
365 uint3 m_num_ghost_cells
; //!< Number of ghost cells in every direction
366 Scalar3 m_ghost_width
; //!< Width of ghost cells
368 // values computed by compute()
369 GPUArray
<unsigned int> m_cell_size
; //!< Number of members in each cell
370 GPUArray
<unsigned int> m_cell_adj
; //!< Cell adjacency list
371 GPUArray
<Scalar4
> m_xyzf
; //!< Cell list with position and flags
372 GPUArray
<Scalar4
> m_tdb
; //!< Cell list with type,diameter,body
373 GPUArray
<Scalar4
> m_orientation
; //!< Cell list with orientation
374 GPUArray
<unsigned int> m_idx
; //!< Cell list with index
375 GPUFlags
<uint3
> m_conditions
; //!< Condition flags set during the computeCellList() call
376 boost::signals2::connection m_sort_connection
; //!< Connection to the ParticleData sort signal
377 boost::signals2::connection m_boxchange_connection
; //!< Connection to the ParticleData box size change signal
379 //! Computes what the dimensions should me
380 uint3
computeDimensions();
382 //! Initialize width and indexers, allocates memory
383 void initializeAll();
386 void initializeWidth();
388 //! Initialize indexers and allocate memory
389 void initializeMemory();
391 //! Initializes values in the cell_adj array
392 void initializeCellAdj();
394 //! Compute the cell list
395 virtual void computeCellList();
397 //! Check the status of the conditions
398 bool checkConditions();
400 //! Reads back the conditions
401 virtual uint3
readConditions();
403 //! Resets the condition status
404 virtual void resetConditions();
407 //! Export the CellList class to python
408 void export_CellList();