src/gromacs/math/multidimarray.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2019,2020, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \libinternal
  36  * \file
  37  * \brief Declares MultiDimArray.
  38  *
  39  * \author Christian Blau <cblau@gwdg.de>
  40  * \ingroup module_math
  41  * \ingroup module_mdspan
  42  * \inlibraryapi
  43  */
  44
  45 #ifndef GMX_MATH_MULTIDIMARRAY_H_
  46 #define GMX_MATH_MULTIDIMARRAY_H_
  47
  48 #include "gromacs/mdspan/mdspan.h"
  49 #include "gromacs/utility/arrayref.h"
  50
  51 namespace gmx
  52 {
  53
  54 namespace detail
  55 {
  56 //! Same as std::void_t from C++17
  57 template<class...>
  58 using void_t = void;
  59
  60 template<typename T, typename = void>
  61 struct is_resizable : std::false_type
  62 {
  63 };
  64
  65 template<typename T>
  66 struct is_resizable<T, void_t<decltype(std::declval<T>().resize(size_t()))>> : std::true_type
  67 {
  68 };
  69
  70 //! Type has a resize member function callable with size_t argument
  71 template<typename T>
  72 // NOLINTNEXTLINE misc-definitions-in-headers
  73 constexpr bool is_resizable_v = is_resizable<T>::value;
  74 } // namespace detail
  75
  76 /*! \libinternal \brief
  77  * Multidimensional array that manages its own memory.
  78  *
  79  * \note No bounds checking when accessing memory
  80  *
  81  * \note That the view holds a valid pointer to the data is a class invariant.
  82  *
  83  * The Container type that stores the data may be resizable (std::vector or similar)
  84  * or static (std::array or similar). Copy and move assignment routines as well as
  85  * swapping are designed to yield good performances in both cases, notably
  86  * foregoing the copy-swap idiom due to the bad performance in swapping std::array.
  87  *
  88  * This class avoids throwing exeptions, apart from the ones that might be thrown
  89  * from the containers during resizing an allocation. (bad_malloc from std::vector
  90  * is a likely candidate)
  91  *
  92  *
  93  * Holds as many elements as required by a multidimensional view.
  94  * \tparam TContainer   Data type container for the data to be stored
  95  *                      as MultiDimArray with random element access and
  96  *                      value_type, refence and const_reference exposed
  97  * \tparam Extents      An extents class describing the array dimensions
  98  *                      as used in module_mdspan
  99  * \tparam LayoutPolicy The data layout as in module_mdspan describes
 100  *                      translation of indices to memory offset.
 101  *                      Defaults to right aligned, so that the right-most index
 102  *                      is contiguous in memory.
 103  */
 104 template<class TContainer, class Extents, class LayoutPolicy = layout_right>
 105 class MultiDimArray
 106 {
 107 public:
 108     //! the type of values that are stored
 109     using value_type = typename TContainer::value_type;
 110     //! reference type to the stored values
 111     using reference = typename TContainer::reference;
 112     //! const reference type to the stored values
 113     using const_reference = typename TContainer::const_reference;
 114     //! the view used to access the data
 115     using view_type = basic_mdspan<value_type, Extents, LayoutPolicy>;
 116     //! const view on the data
 117     using const_view_type = basic_mdspan<const value_type, Extents, LayoutPolicy>;
 118     /*! \brief Iterator type for contiguous iteration over the stored data.
 119      * Used, e.g., in free begin and end functions
 120      */
 121     using iterator = typename ArrayRef<value_type>::iterator;
 122     /*! \brief Const iterator type for contiguous iteration over the stored data.
 123      *  used, e.g., in free begin and end functions
 124      */
 125     using const_iterator = const typename ArrayRef<const value_type>::const_iterator;
 126
 127     static_assert(detail::is_resizable_v<TContainer> == (Extents::rank_dynamic() > 0),
 128                   "Resizable container (e.g. std::vector) requires at least one dynamic rank. "
 129                   "Non-resizable container (e.g. std::array) requires zero dynamic ranks.");
 130
 131     /*! \brief
 132      * Allocate dynamic array data and set view with the dynamic extents.
 133      *
 134      * \param[in] dynamicExtent A parameter pack that describes the dynamic
 135      *                          size of the array. Empty if purely static.
 136      *
 137      * \tparam IndexType        Parameter pack type holding the dynamic
 138      *                          extents of the multidimensional array
 139      */
 140     template<class... IndexType, typename T = TContainer, typename = typename std::enable_if_t<detail::is_resizable_v<T>>>
 141     MultiDimArray(IndexType... dynamicExtent)
 142     {
 143         resize(dynamicExtent...);
 144     }
 145     /*! \brief
 146      * Construction from fixed sized arrays if the array size is static and
 147      * layout policy allows compile time determination of the container size.
 148      *
 149      * Enables the expected initialization
 150      * MultiDimArray<std::array<float, 9>, extents<3,3>> arr = {{1,2...}}
 151      * \tparam T Template parameter for activation via SFINAE.
 152      */
 153     // SFINAE required because std::vector::size isn't constexpr and is_constexpr doesn't exist.
 154     template<typename T = TContainer, typename = typename std::enable_if_t<!detail::is_resizable_v<T>>>
 155     constexpr MultiDimArray(const TContainer& data = {}) noexcept : data_(data), view_(data_.data())
 156     {
 157         static_assert(TContainer().size() == typename view_type::mapping_type().required_span_size(),
 158                       "Non-resizable container type size must match static MultiDimArray size.");
 159     }
 160     //! Copy constructor
 161     constexpr MultiDimArray(const MultiDimArray& o) :
 162         data_(o.data_),
 163         view_(data_.data(), o.view_.extents())
 164     {
 165     }
 166     //! Move constructor
 167     MultiDimArray(MultiDimArray&& o) noexcept :
 168         data_(std::move(o.data_)),
 169         view_(data_.data(), o.view_.extents())
 170     {
 171     }
 172     //! Copy assignment
 173     MultiDimArray& operator=(const MultiDimArray& o)
 174     {
 175         data_ = o.data_;
 176         view_ = view_type(data_.data(), o.view_.extents());
 177         return *this;
 178     }
 179     //! Move assignment
 180     MultiDimArray& operator=(MultiDimArray&& o) noexcept
 181     {
 182         data_ = std::move(o.data_);
 183         view_ = view_type(data_.data(), o.view_.extents());
 184         return *this;
 185     }
 186     //! Swaps content with other
 187     void swap(MultiDimArray& o)
 188     {
 189         using std::swap;
 190         swap(data_, o.data_);
 191         // swap(view_, o.view_) also swaps the pointer to the data and thus does not work
 192         // instead, restore the view as class invariant after the data swapping operation
 193         o.view_ = view_type(o.data_.data(), view_.extents());
 194         view_   = view_type(data_.data(), o.view_.extents());
 195     }
 196     /*! \brief
 197      * Resize the dynamic extents of the array if any and set container size
 198      * accordingly.
 199      *
 200      * Invalidates data and views of this array.
 201      *
 202      * \param[in] dynamicExtent A parameter pack that describes the dynamic
 203      *                          size of the array. Empty if purely static.
 204      * \tparam IndexType        Parameter pack type holding the dynamic
 205      *                          extents of the multidimensional array
 206      */
 207     template<class... IndexType>
 208     void resize(IndexType... dynamicExtent)
 209     {
 210         // use a mapping object to determine the required span size;
 211         layout_right::mapping<Extents> map{ Extents{ dynamicExtent... } };
 212         data_.resize(map.required_span_size());
 213         // to construct a valid view on the data, the container has to be resized before
 214         // the assignment, so that data_.data() is valid
 215         view_ = view_type(data_.data(), dynamicExtent...);
 216     }
 217     /*! \brief Data access via multidimensional indices.
 218      * This allows referencing rank R array elements as array(x_0,x_1,x_2, .., x_R)
 219      *
 220      * \param[in] index multidimensional indices as parameter pack
 221      *                  the number of parameters must match the rank of the array.
 222      *
 223      * \returns reference to array element
 224      */
 225     template<class... IndexType>
 226     reference operator()(IndexType... index) noexcept
 227     {
 228         return view_(index...);
 229     }
 230     /*! \brief Const data access via multidimensional indices.
 231      * This allows referencing rank R array elements as array(x_0,x_1,x_2, .., x_R)
 232      *
 233      * \param[in] index multidimensional indices as parameter pack
 234      *                  the number of parameters must match the rank of the array.
 235      *
 236      * \returns const reference to array element
 237      */
 238     template<class... IndexType>
 239     constexpr const_reference operator()(IndexType... index) const noexcept
 240     {
 241         return view_(index...);
 242     }
 243     /*! \brief Contiguous access to the data.
 244      * \returns ArrayRef to stored data.
 245      */
 246     ArrayRef<value_type> toArrayRef() { return { data_.data(), data_.data() + data_.size() }; }
 247     /*! \brief Contiguous const access to the data.
 248      * \returns ArrayRef to stored data.
 249      */
 250     constexpr ArrayRef<const value_type> toArrayRef() const
 251     {
 252         return { data_.data(), data_.data() + data_.size() };
 253     }
 254     /*! \brief Return the extent.
 255      * \param[in] k dimension to query for extent
 256      * \returns extent along specified dimension
 257      */
 258     constexpr typename view_type::index_type extent(int k) const noexcept
 259     {
 260         return view_.extent(k);
 261     }
 262     //! Conversion to multidimensional view on the data
 263     constexpr view_type asView() noexcept { return view_; }
 264     //! Conversion to const multidimensional view on the data
 265     constexpr const_view_type asConstView() const noexcept
 266     {
 267         return { data_.data(), view_.mapping() };
 268     }
 269
 270 private:
 271     //! The contiguous data that is equipped with multidimensional indexing in this class
 272     TContainer data_;
 273     //! Multidimensional view into data_.
 274     view_type view_;
 275 };
 276
 277 //! Free MultiDimArray begin function addressing its contiguous memory.
 278 template<class TContainer, class Extents>
 279 constexpr typename MultiDimArray<TContainer, Extents>::const_iterator
 280 begin(const MultiDimArray<TContainer, Extents>& multiDimArray)
 281 {
 282     return multiDimArray.toArrayRef().begin();
 283 }
 284
 285 //! Free MultiDimArray begin function addressing its contiguous memory.
 286 template<class TContainer, class Extents>
 287 constexpr typename MultiDimArray<TContainer, Extents>::iterator begin(MultiDimArray<TContainer, Extents>& multiDimArray)
 288 {
 289     return multiDimArray.toArrayRef().begin();
 290 }
 291
 292 //! Free MultiDimArray end function addressing its contiguous memory.
 293 template<class TContainer, class Extents>
 294 constexpr typename MultiDimArray<TContainer, Extents>::const_iterator
 295 end(const MultiDimArray<TContainer, Extents>& multiDimArray)
 296 {
 297     return multiDimArray.toArrayRef().end();
 298 }
 299
 300 //! Free MultiDimArray end function addressing its contiguous memory.
 301 template<class TContainer, class Extents>
 302 constexpr typename MultiDimArray<TContainer, Extents>::iterator end(MultiDimArray<TContainer, Extents>& multiDimArray)
 303 {
 304     return multiDimArray.toArrayRef().end();
 305 }
 306
 307 //! Swap function
 308 template<class TContainer, class Extents>
 309 void swap(MultiDimArray<TContainer, Extents>& a, MultiDimArray<TContainer, Extents>& b) noexcept
 310 {
 311     a.swap(b);
 312 }
 313
 314 } // namespace gmx
 315
 316 #endif // GMX_MATH_MULTIDIMARRAY_H_