src/gromacs/math/vectypes.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2013,2014, by the GROMACS development team, led by
   7  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   8  * and including many others, as listed in the AUTHORS file in the
   9  * top-level source directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37 #ifndef GMX_MATH_VECTYPES_H
  38 #define GMX_MATH_VECTYPES_H
  39
  40 #include "gromacs/utility/real.h"
  41
  42 #define XX      0 /* Defines for indexing in */
  43 #define YY      1 /* vectors                 */
  44 #define ZZ      2
  45 #define DIM     3 /* Dimension of vectors    */
  46
  47 typedef real    rvec[DIM];
  48
  49 typedef double  dvec[DIM];
  50
  51 typedef real    matrix[DIM][DIM];
  52
  53 typedef real    tensor[DIM][DIM];
  54
  55 typedef int     ivec[DIM];
  56
  57 typedef int     imatrix[DIM][DIM];
  58
  59 #ifdef __cplusplus
  60
  61 namespace gmx
  62 {
  63
  64 /*! \brief
  65  * C++ class for 3D vectors.
  66  *
  67  * \tparam ValueType  Type
  68  *
  69  * This class provides a C++ version of rvec/dvec/ivec that can be put into STL
  70  * containers etc.  It is more or less a drop-in replacement for `rvec` and
  71  * friends: it can be used in most contexts that accept the equivalent C type.
  72  * However, there are two cases where explicit conversion is necessary:
  73  *  - An array of these objects needs to be converted with as_vec_array() (or
  74  *    convenience methods like as_rvec_array()).
  75  *  - Passing an RVec as a `const rvec &` parameter to a function needs an
  76  *    explicit call to as_vec().  The implicit conversion should work for this
  77  *    as well, but cppcheck parses the necessary implicit conversion operator
  78  *    incorrectly and MSVC fails to compile code that relies on the implicit
  79  *    conversion, so the explicit method is necessary.
  80  *
  81  * For the array conversion to work, the compiler should not add any extra
  82  * alignment/padding in the layout of this class;  that this actually works as
  83  * intended is tested in the unit tests.
  84  *
  85  * \inpublicapi
  86  */
  87 template <typename ValueType>
  88 class BasicVector
  89 {
  90     public:
  91         //! Underlying raw C array type (rvec/dvec/ivec).
  92         typedef ValueType RawArray[DIM];
  93
  94         //! Constructs default (uninitialized) vector.
  95         BasicVector() {}
  96         //! Constructs a vector from given values.
  97         BasicVector(ValueType x, ValueType y, ValueType z)
  98         {
  99             x_[XX] = x;
 100             x_[YY] = y;
 101             x_[ZZ] = z;
 102         }
 103         /*! \brief
 104          * Constructs a vector from given values.
 105          *
 106          * This constructor is not explicit to support implicit conversions
 107          * that allow, e.g., calling `std::vector<RVec>:``:push_back()` directly
 108          * with an `rvec` parameter.
 109          */
 110         BasicVector(const RawArray x)
 111         {
 112             x_[XX] = x[XX];
 113             x_[YY] = x[YY];
 114             x_[ZZ] = x[ZZ];
 115         }
 116         //! Indexing operator to make the class work as the raw array.
 117         ValueType &operator[](int i) { return x_[i]; }
 118         //! Indexing operator to make the class work as the raw array.
 119         ValueType operator[](int i) const { return x_[i]; }
 120         // The conversion functions below could more accurately return
 121         // RawArray &, but this fails with cppcheck and does not solve the
 122         // issue with MSVC, so as_vec() should be used instead.
 123         //! Makes BasicVector usable in contexts where a raw C array is expected.
 124         operator ValueType *() { return x_; }
 125         //! Makes BasicVector usable in contexts where a raw C array is expected.
 126         operator const ValueType *() const { return x_; }
 127
 128         //! Converts to a raw C array where implicit conversion does not work.
 129         RawArray &as_vec() { return x_; }
 130         //! Converts to a raw C array where implicit conversion does not work.
 131         const RawArray &as_vec() const { return x_; }
 132
 133     private:
 134         RawArray x_;
 135 };
 136
 137 /*! \brief
 138  * Casts a gmx::BasicVector array into an equivalent raw C array.
 139  */
 140 template <typename ValueType> static inline
 141 typename BasicVector<ValueType>::RawArray *
 142 as_vec_array(BasicVector<ValueType> *x)
 143 {
 144     return reinterpret_cast<typename BasicVector<ValueType>::RawArray *>(x);
 145 }
 146
 147 /*! \brief
 148  * Casts a gmx::BasicVector array into an equivalent raw C array.
 149  */
 150 template <typename ValueType> static inline
 151 const typename BasicVector<ValueType>::RawArray *
 152 as_vec_array(const BasicVector<ValueType> *x)
 153 {
 154     return reinterpret_cast<const typename BasicVector<ValueType>::RawArray *>(x);
 155 }
 156
 157 //! Shorthand for C++ `rvec`-equivalent type.
 158 typedef BasicVector<real> RVec;
 159 //! Casts a gmx::RVec array into an `rvec` array.
 160 static inline rvec *as_rvec_array(RVec *x)
 161 {
 162     return as_vec_array(x);
 163 }
 164 //! Casts a gmx::RVec array into an `rvec` array.
 165 static inline const rvec *as_rvec_array(const RVec *x)
 166 {
 167     return as_vec_array(x);
 168 }
 169
 170 } // namespace gmx
 171
 172 #endif
 173
 174 #endif