ceph/src/boost/boost/python/numpy/ndarray.hpp

   1 // Copyright Jim Bosch 2010-2012.
   2 // Copyright Stefan Seefeld 2016.
   3 // Distributed under the Boost Software License, Version 1.0.
   4 // (See accompanying file LICENSE_1_0.txt or copy at
   5 // http://www.boost.org/LICENSE_1_0.txt)
   6
   7 #ifndef boost_python_numpy_ndarray_hpp_
   8 #define boost_python_numpy_ndarray_hpp_
   9
  10 /**
  11  *  @brief Object manager and various utilities for numpy.ndarray.
  12  */
  13
  14 #include <boost/python.hpp>
  15 #include <boost/utility/enable_if.hpp>
  16 #include <boost/python/detail/type_traits.hpp>
  17 #include <boost/python/numpy/numpy_object_mgr_traits.hpp>
  18 #include <boost/python/numpy/dtype.hpp>
  19 #include <boost/python/numpy/config.hpp>
  20
  21 #include <vector>
  22
  23 namespace boost { namespace python { namespace numpy {
  24
  25 /**
  26  *  @brief A boost.python "object manager" (subclass of object) for numpy.ndarray.
  27  *
  28  *  @todo This could have a lot more functionality (like boost::python::numeric::array).
  29  *        Right now all that exists is what was needed to move raw data between C++ and Python.
  30  */
  31
  32 class BOOST_NUMPY_DECL ndarray : public object
  33 {
  34
  35   /**
  36    *  @brief An internal struct that's byte-compatible with PyArrayObject.
  37    *
  38    *  This is just a hack to allow inline access to this stuff while hiding numpy/arrayobject.h
  39    *  from the user.
  40    */
  41   struct array_struct
  42   {
  43     PyObject_HEAD
  44     char * data;
  45     int nd;
  46     Py_intptr_t * shape;
  47     Py_intptr_t * strides;
  48     PyObject * base;
  49     PyObject * descr;
  50     int flags;
  51     PyObject * weakreflist;
  52   };
  53
  54   /// @brief Return the held Python object as an array_struct.
  55   array_struct * get_struct() const { return reinterpret_cast<array_struct*>(this->ptr()); }
  56
  57 public:
  58
  59   /**
  60    *  @brief Enum to represent (some) of Numpy's internal flags.
  61    *
  62    *  These don't match the actual Numpy flag values; we can't get those without including
  63    *  numpy/arrayobject.h or copying them directly.  That's very unfortunate.
  64    *
  65    *  @todo I'm torn about whether this should be an enum.  It's very convenient to not
  66    *        make these simple integer values for overloading purposes, but the need to
  67    *        define every possible combination and custom bitwise operators is ugly.
  68    */
  69   enum bitflag
  70   {
  71     NONE=0x0, C_CONTIGUOUS=0x1, F_CONTIGUOUS=0x2, V_CONTIGUOUS=0x1|0x2,
  72     ALIGNED=0x4, WRITEABLE=0x8, BEHAVED=0x4|0x8,
  73     CARRAY_RO=0x1|0x4, CARRAY=0x1|0x4|0x8, CARRAY_MIS=0x1|0x8,
  74     FARRAY_RO=0x2|0x4, FARRAY=0x2|0x4|0x8, FARRAY_MIS=0x2|0x8,
  75     UPDATE_ALL=0x1|0x2|0x4, VARRAY=0x1|0x2|0x8, ALL=0x1|0x2|0x4|0x8
  76   };
  77
  78   BOOST_PYTHON_FORWARD_OBJECT_CONSTRUCTORS(ndarray, object);
  79
  80   /// @brief Return a view of the scalar with the given dtype.
  81   ndarray view(dtype const & dt) const;
  82
  83   /// @brief Copy the array, cast to a specified type.
  84   ndarray astype(dtype const & dt) const;
  85
  86   /// @brief Copy the scalar (deep for all non-object fields).
  87   ndarray copy() const;
  88
  89   /// @brief Return the size of the nth dimension. raises IndexError if k not in [-get_nd() : get_nd()-1 ]
  90   Py_intptr_t shape(int n) const;
  91
  92   /// @brief Return the stride of the nth dimension. raises IndexError if k not in [-get_nd() : get_nd()-1]
  93   Py_intptr_t strides(int n) const;
  94
  95   /**
  96    *  @brief Return the array's raw data pointer.
  97    *
  98    *  This returns char so stride math works properly on it.  It's pretty much
  99    *  expected that the user will have to reinterpret_cast it.
 100    */
 101   char * get_data() const { return get_struct()->data; }
 102
 103   /// @brief Return the array's data-type descriptor object.
 104   dtype get_dtype() const;
 105
 106   /// @brief Return the object that owns the array's data, or None if the array owns its own data.
 107   object get_base() const;
 108
 109   /// @brief Set the object that owns the array's data.  Use with care.
 110   void set_base(object const & base);
 111
 112   /// @brief Return the shape of the array as an array of integers (length == get_nd()).
 113   Py_intptr_t const * get_shape() const { return get_struct()->shape; }
 114
 115   /// @brief Return the stride of the array as an array of integers (length == get_nd()).
 116   Py_intptr_t const * get_strides() const { return get_struct()->strides; }
 117
 118   /// @brief Return the number of array dimensions.
 119   int get_nd() const { return get_struct()->nd; }
 120
 121   /// @brief Return the array flags.
 122   bitflag get_flags() const;
 123
 124   /// @brief Reverse the dimensions of the array.
 125   ndarray transpose() const;
 126
 127   /// @brief Eliminate any unit-sized dimensions.
 128   ndarray squeeze() const;
 129
 130   /// @brief Equivalent to self.reshape(*shape) in Python.
 131   ndarray reshape(python::tuple const & shape) const;
 132
 133   /**
 134    *  @brief If the array contains only a single element, return it as an array scalar; otherwise return
 135    *         the array.
 136    *
 137    *  @internal This is simply a call to PyArray_Return();
 138    */
 139   object scalarize() const;
 140 };
 141
 142 /**
 143  *  @brief Construct a new array with the given shape and data type, with data initialized to zero.
 144  */
 145 BOOST_NUMPY_DECL ndarray zeros(python::tuple const & shape, dtype const & dt);
 146 BOOST_NUMPY_DECL ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt);
 147
 148 /**
 149  *  @brief Construct a new array with the given shape and data type, with data left uninitialized.
 150  */
 151 BOOST_NUMPY_DECL ndarray empty(python::tuple const & shape, dtype const & dt);
 152 BOOST_NUMPY_DECL ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt);
 153
 154 /**
 155  *  @brief Construct a new array from an arbitrary Python sequence.
 156  *
 157  *  @todo This does't seem to handle ndarray subtypes the same way that "numpy.array" does in Python.
 158  */
 159 BOOST_NUMPY_DECL ndarray array(object const & obj);
 160 BOOST_NUMPY_DECL ndarray array(object const & obj, dtype const & dt);
 161
 162 namespace detail
 163 {
 164
 165 BOOST_NUMPY_DECL ndarray from_data_impl(void * data,
 166                                         dtype const & dt,
 167                                         std::vector<Py_intptr_t> const & shape,
 168                                         std::vector<Py_intptr_t> const & strides,
 169                                         object const & owner,
 170                                         bool writeable);
 171
 172 template <typename Container>
 173 ndarray from_data_impl(void * data,
 174                        dtype const & dt,
 175                        Container shape,
 176                        Container strides,
 177                        object const & owner,
 178                        bool writeable,
 179                        typename boost::enable_if< boost::python::detail::is_integral<typename Container::value_type> >::type * enabled = NULL)
 180 {
 181   std::vector<Py_intptr_t> shape_(shape.begin(),shape.end());
 182   std::vector<Py_intptr_t> strides_(strides.begin(), strides.end());
 183   return from_data_impl(data, dt, shape_, strides_, owner, writeable);
 184 }
 185
 186 BOOST_NUMPY_DECL ndarray from_data_impl(void * data,
 187                                         dtype const & dt,
 188                                         object const & shape,
 189                                         object const & strides,
 190                                         object const & owner,
 191                                         bool writeable);
 192
 193 } // namespace boost::python::numpy::detail
 194
 195 /**
 196  *  @brief Construct a new ndarray object from a raw pointer.
 197  *
 198  *  @param[in] data    Raw pointer to the first element of the array.
 199  *  @param[in] dt      Data type descriptor.  Often retrieved with dtype::get_builtin().
 200  *  @param[in] shape   Shape of the array as STL container of integers; must have begin() and end().
 201  *  @param[in] strides Shape of the array as STL container of integers; must have begin() and end().
 202  *  @param[in] owner   An arbitray Python object that owns that data pointer.  The array object will
 203  *                     keep a reference to the object, and decrement it's reference count when the
 204  *                     array goes out of scope.  Pass None at your own peril.
 205  *
 206  *  @todo Should probably take ranges of iterators rather than actual container objects.
 207  */
 208 template <typename Container>
 209 inline ndarray from_data(void * data,
 210                          dtype const & dt,
 211                          Container shape,
 212                          Container strides,
 213                          python::object const & owner)
 214 {
 215   return numpy::detail::from_data_impl(data, dt, shape, strides, owner, true);
 216 }
 217
 218 /**
 219  *  @brief Construct a new ndarray object from a raw pointer.
 220  *
 221  *  @param[in] data    Raw pointer to the first element of the array.
 222  *  @param[in] dt      Data type descriptor.  Often retrieved with dtype::get_builtin().
 223  *  @param[in] shape   Shape of the array as STL container of integers; must have begin() and end().
 224  *  @param[in] strides Shape of the array as STL container of integers; must have begin() and end().
 225  *  @param[in] owner   An arbitray Python object that owns that data pointer.  The array object will
 226  *                     keep a reference to the object, and decrement it's reference count when the
 227  *                     array goes out of scope.  Pass None at your own peril.
 228  *
 229  *  This overload takes a const void pointer and sets the "writeable" flag of the array to false.
 230  *
 231  *  @todo Should probably take ranges of iterators rather than actual container objects.
 232  */
 233 template <typename Container>
 234 inline ndarray from_data(void const * data,
 235                          dtype const & dt,
 236                          Container shape,
 237                          Container strides,
 238                          python::object const & owner)
 239 {
 240   return numpy::detail::from_data_impl(const_cast<void*>(data), dt, shape, strides, owner, false);
 241 }
 242
 243 /**
 244  *  @brief Transform an arbitrary object into a numpy array with the given requirements.
 245  *
 246  *  @param[in] obj     An arbitrary python object to convert.  Arrays that meet the requirements
 247  *                     will be passed through directly.
 248  *  @param[in] dt      Data type descriptor.  Often retrieved with dtype::get_builtin().
 249  *  @param[in] nd_min  Minimum number of dimensions.
 250  *  @param[in] nd_max  Maximum number of dimensions.
 251  *  @param[in] flags   Bitwise OR of flags specifying additional requirements.
 252  */
 253 BOOST_NUMPY_DECL ndarray from_object(object const & obj,
 254                                      dtype const & dt,
 255                                      int nd_min,
 256                                      int nd_max,
 257                                      ndarray::bitflag flags=ndarray::NONE);
 258
 259 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
 260                                             dtype const & dt,
 261                                             int nd,
 262                                             ndarray::bitflag flags=ndarray::NONE)
 263 {
 264   return from_object(obj, dt, nd, nd, flags);
 265 }
 266
 267 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
 268                                             dtype const & dt,
 269                                             ndarray::bitflag flags=ndarray::NONE)
 270 {
 271   return from_object(obj, dt, 0, 0, flags);
 272 }
 273
 274 BOOST_NUMPY_DECL ndarray from_object(object const & obj,
 275                                      int nd_min,
 276                                      int nd_max,
 277                                      ndarray::bitflag flags=ndarray::NONE);
 278
 279 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
 280                                             int nd,
 281                                             ndarray::bitflag flags=ndarray::NONE)
 282 {
 283   return from_object(obj, nd, nd, flags);
 284 }
 285
 286 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
 287                                             ndarray::bitflag flags=ndarray::NONE)
 288 {
 289   return from_object(obj, 0, 0, flags);
 290 }
 291
 292 BOOST_NUMPY_DECL inline ndarray::bitflag operator|(ndarray::bitflag a,
 293                                                    ndarray::bitflag b)
 294 {
 295   return ndarray::bitflag(int(a) | int(b));
 296 }
 297
 298 BOOST_NUMPY_DECL inline ndarray::bitflag operator&(ndarray::bitflag a,
 299                                                    ndarray::bitflag b)
 300 {
 301   return ndarray::bitflag(int(a) & int(b));
 302 }
 303
 304 } // namespace boost::python::numpy
 305
 306 namespace converter
 307 {
 308
 309 NUMPY_OBJECT_MANAGER_TRAITS(numpy::ndarray);
 310
 311 }}} // namespace boost::python::converter
 312
 313 #endif