libhoomd/utils/Index1D.h

   1 /*
   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.
   5
   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.
   9
  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:
  12
  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.
  16
  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.
  20
  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
  25
  26 * Any electronic documents citing HOOMD-Blue will link to the HOOMD-Blue website:
  27 http://codeblue.umich.edu/hoomd-blue/
  28
  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
  32 permission.
  33
  34 Disclaimer
  35
  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.
  40
  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.
  48 */
  49
  50 // Maintainer: joaander
  51
  52 #ifndef __INDEX1D_H__
  53 #define __INDEX1D_H__
  54
  55 /*! \file Index1D.h
  56     \brief Defines utility classes for 1D indexing of multi-dimensional arrays
  57     \details These are very low-level, high performance functions. No error checking is performed on their arguments,
  58     even in debug mode. They are provided mainly as a convenience. The col,row ordering is unorthodox for normal
  59     matrices, but is consistent with the tex2D x,y access pattern used in CUDA. The decision is to go with x,y for
  60     consistency.
  61 */
  62
  63 #include "HOOMDMath.h"
  64
  65 // need to declare these classes with __host__ __device__ qualifiers when building in nvcc
  66 // HOSTDEVICE is __host__ __device__ when included in nvcc and blank when included into the host compiler
  67 #ifdef NVCC
  68 #define HOSTDEVICE __host__ __device__
  69 #else
  70 #define HOSTDEVICE
  71 #endif
  72
  73 //! Index a 2D array
  74 /*! Row major mapping of 2D onto 1D
  75     \ingroup utils
  76 */
  77 class Index2D
  78     {
  79     public:
  80         //! Contstructor
  81         /*! \param w Width of the square 2D array
  82         */
  83         HOSTDEVICE inline Index2D(unsigned int w=0) : m_w(w), m_h(w) {}
  84
  85         //! Contstructor
  86         /*! \param w Width of the rectangular 2D array
  87             \param h Height of the rectangular 2D array
  88         */
  89         HOSTDEVICE inline Index2D(unsigned int w, unsigned int h) : m_w(w), m_h(h) {}
  90
  91         //! Calculate an index
  92         /*! \param i column index
  93             \param j row index
  94             \returns 1D array index corresponding to the 2D index (\a i, \a j) in row major order
  95         */
  96         HOSTDEVICE inline unsigned int operator()(unsigned int i, unsigned int j) const
  97             {
  98             return j*m_w + i;
  99             }
 100
 101         //! Get the number of 1D elements stored
 102         /*! \returns Number of elements stored in the underlying 1D array
 103         */
 104         HOSTDEVICE inline unsigned int getNumElements() const
 105             {
 106             return m_w*m_h;
 107             }
 108
 109         //! Get the width of the 2D array
 110         HOSTDEVICE inline unsigned int getW() const
 111             {
 112             return m_w;
 113             }
 114
 115         //! Get the height of the 2D array
 116         HOSTDEVICE inline unsigned int getH() const
 117             {
 118             return m_h;
 119             }
 120
 121     private:
 122         unsigned int m_w;   //!< Width of the 2D array
 123         unsigned int m_h;   //!< Height of the 2D array
 124     };
 125
 126 //! Index a 3D array
 127 /*! Row major mapping of 3D onto 1D
 128     \ingroup utils
 129 */
 130 class Index3D
 131     {
 132     public:
 133         //! Contstructor
 134         /*! \param w Width of the square 3D array
 135         */
 136         HOSTDEVICE inline Index3D(unsigned int w=0) : m_w(w), m_h(w), m_d(w) {}
 137
 138         //! Contstructor
 139         /*! \param w Width of the rectangular 3D array
 140             \param h Height of the rectangular 3D array
 141             \param d Depth of the rectangular 3D array
 142         */
 143         HOSTDEVICE inline Index3D(unsigned int w, unsigned int h, unsigned int d) : m_w(w), m_h(h), m_d(d) {}
 144
 145         //! Calculate an index
 146         /*! \param i column index (along width)
 147             \param j row index (along height)
 148             \param k plane index (along depth)
 149             \returns 1D array index corresponding to the 2D index (\a i, \a j) in row major order
 150         */
 151         HOSTDEVICE inline unsigned int operator()(unsigned int i, unsigned int j, unsigned int k) const
 152             {
 153             return (k*m_h + j)*m_w + i;
 154             }
 155
 156         //! Get the number of 1D elements stored
 157         /*! \returns Number of elements stored in the underlying 1D array
 158         */
 159         HOSTDEVICE inline unsigned int getNumElements() const
 160             {
 161             return m_w * m_h * m_d;
 162             }
 163
 164         //! Get the width of the 3D array
 165         HOSTDEVICE inline unsigned int getW() const
 166             {
 167             return m_w;
 168             }
 169
 170         //! Get the height of the 3D array
 171         HOSTDEVICE inline unsigned int getH() const
 172             {
 173             return m_h;
 174             }
 175
 176         //! Get the depth of the 3D array
 177         HOSTDEVICE inline unsigned int getD() const
 178             {
 179             return m_d;
 180             }
 181
 182         //! Get the inverse mapping 1D-index -> coordinate tuple
 183         HOSTDEVICE inline uint3 getTriple(const unsigned int idx) const
 184             {
 185             uint3 t;
 186
 187             t.z = idx / (m_h*m_w);
 188             t.y = (idx % (m_h*m_w)) / m_w;
 189             t.x = idx - t.z * m_h *m_w - t.y * m_w;
 190             return t;
 191             }
 192
 193     private:
 194         unsigned int m_w;   //!< Width of the 3D array
 195         unsigned int m_h;   //!< Height of the 3D array
 196         unsigned int m_d;   //!< Depth of the 3D array
 197     };
 198
 199 //! Index a 2D upper triangular array
 200 /*! Row major mapping of a 2D upper triangular array onto 1D
 201     \ingroup utils
 202 */
 203 class Index2DUpperTriangular
 204     {
 205     public:
 206         //! Contstructor
 207         /*! \param w Width of the 2D upper triangular array
 208         */
 209         HOSTDEVICE inline Index2DUpperTriangular(unsigned int w=0) : m_w(w)
 210             {
 211             m_term = 2*m_w - 1;
 212             }
 213
 214         //! Calculate an index
 215         /*! \param i column index
 216             \param j row index
 217             \returns 1D array index corresponding to the 2D index (\a i, \a j) in row major order
 218             \note Forumla adapted from: http://www.itl.nist.gov/div897/sqg/dads/HTML/upperTriangularMatrix.html
 219         */
 220         HOSTDEVICE inline unsigned int operator()(unsigned int i, unsigned int j) const
 221             {
 222             // swap if j > i
 223             if (j > i)
 224                 {
 225                 unsigned int tmp = i;
 226                 i = j;
 227                 j = tmp;
 228                 }
 229             return j * (m_term - j) / 2 + i;
 230             }
 231
 232         //! Get the number of 1D elements stored
 233         /*! \returns Number of elements stored in the underlying 1D array
 234         */
 235         HOSTDEVICE inline unsigned int getNumElements() const
 236             {
 237             return m_w*(m_w+1) / 2;
 238             }
 239
 240     private:
 241         unsigned int m_w;     //!< Width of the 2D upper triangular array
 242         unsigned int m_term;  //!< Precomputed term of the equation for efficiency
 243     };
 244
 245 #undef HOSTDEVICE
 246 #endif