python/numpy/ndarray.hpp

0001 // Copyright Jim Bosch 2010-2012.
0002 // Copyright Stefan Seefeld 2016.
0003 // Distributed under the Boost Software License, Version 1.0.
0004 // (See accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 #ifndef boost_python_numpy_ndarray_hpp_
0008 #define boost_python_numpy_ndarray_hpp_
0009
0010 /**
0011  *  @brief Object manager and various utilities for numpy.ndarray.
0012  */
0013
0014 #include <boost/python.hpp>
0015 #include <boost/utility/enable_if.hpp>
0016 #include <boost/python/detail/type_traits.hpp>
0017 #include <boost/python/numpy/numpy_object_mgr_traits.hpp>
0018 #include <boost/python/numpy/dtype.hpp>
0019 #include <boost/python/numpy/config.hpp>
0020
0021 #include <vector>
0022
0023 namespace boost { namespace python { namespace numpy {
0024
0025 /**
0026  *  @brief A boost.python "object manager" (subclass of object) for numpy.ndarray.
0027  *
0028  *  @todo This could have a lot more functionality (like boost::python::numeric::array).
0029  *        Right now all that exists is what was needed to move raw data between C++ and Python.
0030  */
0031
0032 class BOOST_NUMPY_DECL ndarray : public object
0033 {
0034
0035   /**
0036    *  @brief An internal struct that's byte-compatible with PyArrayObject.
0037    *
0038    *  This is just a hack to allow inline access to this stuff while hiding numpy/arrayobject.h
0039    *  from the user.
0040    */
0041   struct array_struct
0042   {
0043     PyObject_HEAD
0044     char * data;
0045     int nd;
0046     Py_intptr_t * shape;
0047     Py_intptr_t * strides;
0048     PyObject * base;
0049     PyObject * descr;
0050     int flags;
0051     PyObject * weakreflist;
0052   };
0053
0054   /// @brief Return the held Python object as an array_struct.
0055   array_struct * get_struct() const { return reinterpret_cast<array_struct*>(this->ptr()); }
0056
0057 public:
0058
0059   /**
0060    *  @brief Enum to represent (some) of Numpy's internal flags.
0061    *
0062    *  These don't match the actual Numpy flag values; we can't get those without including
0063    *  numpy/arrayobject.h or copying them directly.  That's very unfortunate.
0064    *
0065    *  @todo I'm torn about whether this should be an enum.  It's very convenient to not
0066    *        make these simple integer values for overloading purposes, but the need to
0067    *        define every possible combination and custom bitwise operators is ugly.
0068    */
0069   enum bitflag
0070   {
0071     NONE=0x0, C_CONTIGUOUS=0x1, F_CONTIGUOUS=0x2, V_CONTIGUOUS=0x1|0x2,
0072     ALIGNED=0x4, WRITEABLE=0x8, BEHAVED=0x4|0x8,
0073     CARRAY_RO=0x1|0x4, CARRAY=0x1|0x4|0x8, CARRAY_MIS=0x1|0x8,
0074     FARRAY_RO=0x2|0x4, FARRAY=0x2|0x4|0x8, FARRAY_MIS=0x2|0x8,
0075     UPDATE_ALL=0x1|0x2|0x4, VARRAY=0x1|0x2|0x8, ALL=0x1|0x2|0x4|0x8
0076   };
0077
0078   BOOST_PYTHON_FORWARD_OBJECT_CONSTRUCTORS(ndarray, object);
0079
0080   /// @brief Return a view of the scalar with the given dtype.
0081   ndarray view(dtype const & dt) const;
0082
0083   /// @brief Copy the array, cast to a specified type.
0084   ndarray astype(dtype const & dt) const;
0085
0086   /// @brief Copy the scalar (deep for all non-object fields).
0087   ndarray copy() const;
0088
0089   /// @brief Return the size of the nth dimension. raises IndexError if k not in [-get_nd() : get_nd()-1 ]
0090   Py_intptr_t shape(int n) const;
0091
0092   /// @brief Return the stride of the nth dimension. raises IndexError if k not in [-get_nd() : get_nd()-1]
0093   Py_intptr_t strides(int n) const;
0094
0095   /**
0096    *  @brief Return the array's raw data pointer.
0097    *
0098    *  This returns char so stride math works properly on it.  It's pretty much
0099    *  expected that the user will have to reinterpret_cast it.
0100    */
0101   char * get_data() const { return get_struct()->data; }
0102
0103   /// @brief Return the array's data-type descriptor object.
0104   dtype get_dtype() const;
0105
0106   /// @brief Return the object that owns the array's data, or None if the array owns its own data.
0107   object get_base() const;
0108
0109   /// @brief Set the object that owns the array's data.  Use with care.
0110   void set_base(object const & base);
0111
0112   /// @brief Return the shape of the array as an array of integers (length == get_nd()).
0113   Py_intptr_t const * get_shape() const { return get_struct()->shape; }
0114
0115   /// @brief Return the stride of the array as an array of integers (length == get_nd()).
0116   Py_intptr_t const * get_strides() const { return get_struct()->strides; }
0117
0118   /// @brief Return the number of array dimensions.
0119   int get_nd() const { return get_struct()->nd; }
0120
0121   /// @brief Return the array flags.
0122   bitflag get_flags() const;
0123
0124   /// @brief Reverse the dimensions of the array.
0125   ndarray transpose() const;
0126
0127   /// @brief Eliminate any unit-sized dimensions.
0128   ndarray squeeze() const;
0129
0130   /// @brief Equivalent to self.reshape(*shape) in Python.
0131   ndarray reshape(python::tuple const & shape) const;
0132
0133   /**
0134    *  @brief If the array contains only a single element, return it as an array scalar; otherwise return
0135    *         the array.
0136    *
0137    *  @internal This is simply a call to PyArray_Return();
0138    */
0139   object scalarize() const;
0140 };
0141
0142 /**
0143  *  @brief Construct a new array with the given shape and data type, with data initialized to zero.
0144  */
0145 BOOST_NUMPY_DECL ndarray zeros(python::tuple const & shape, dtype const & dt);
0146 BOOST_NUMPY_DECL ndarray zeros(int nd, Py_intptr_t const * shape, dtype const & dt);
0147
0148 /**
0149  *  @brief Construct a new array with the given shape and data type, with data left uninitialized.
0150  */
0151 BOOST_NUMPY_DECL ndarray empty(python::tuple const & shape, dtype const & dt);
0152 BOOST_NUMPY_DECL ndarray empty(int nd, Py_intptr_t const * shape, dtype const & dt);
0153
0154 /**
0155  *  @brief Construct a new array from an arbitrary Python sequence.
0156  *
0157  *  @todo This does't seem to handle ndarray subtypes the same way that "numpy.array" does in Python.
0158  */
0159 BOOST_NUMPY_DECL ndarray array(object const & obj);
0160 BOOST_NUMPY_DECL ndarray array(object const & obj, dtype const & dt);
0161
0162 namespace detail
0163 {
0164
0165 BOOST_NUMPY_DECL ndarray from_data_impl(void * data,
0166                     dtype const & dt,
0167                     std::vector<Py_intptr_t> const & shape,
0168                     std::vector<Py_intptr_t> const & strides,
0169                     object const & owner,
0170                     bool writeable);
0171
0172 template <typename Container>
0173 ndarray from_data_impl(void * data,
0174                dtype const & dt,
0175                Container shape,
0176                Container strides,
0177                object const & owner,
0178                bool writeable,
0179                typename boost::enable_if< boost::python::detail::is_integral<typename Container::value_type> >::type * enabled = NULL)
0180 {
0181   std::vector<Py_intptr_t> shape_(shape.begin(),shape.end());
0182   std::vector<Py_intptr_t> strides_(strides.begin(), strides.end());
0183   return from_data_impl(data, dt, shape_, strides_, owner, writeable);
0184 }
0185
0186 BOOST_NUMPY_DECL ndarray from_data_impl(void * data,
0187                     dtype const & dt,
0188                     object const & shape,
0189                     object const & strides,
0190                     object const & owner,
0191                     bool writeable);
0192
0193 } // namespace boost::python::numpy::detail
0194
0195 /**
0196  *  @brief Construct a new ndarray object from a raw pointer.
0197  *
0198  *  @param[in] data    Raw pointer to the first element of the array.
0199  *  @param[in] dt      Data type descriptor.  Often retrieved with dtype::get_builtin().
0200  *  @param[in] shape   Shape of the array as STL container of integers; must have begin() and end().
0201  *  @param[in] strides Shape of the array as STL container of integers; must have begin() and end().
0202  *  @param[in] owner   An arbitray Python object that owns that data pointer.  The array object will
0203  *                     keep a reference to the object, and decrement it's reference count when the
0204  *                     array goes out of scope.  Pass None at your own peril.
0205  *
0206  *  @todo Should probably take ranges of iterators rather than actual container objects.
0207  */
0208 template <typename Container>
0209 inline ndarray from_data(void * data,
0210              dtype const & dt,
0211              Container shape,
0212              Container strides,
0213              python::object const & owner)
0214 {
0215   return numpy::detail::from_data_impl(data, dt, shape, strides, owner, true);
0216 }
0217
0218 /**
0219  *  @brief Construct a new ndarray object from a raw pointer.
0220  *
0221  *  @param[in] data    Raw pointer to the first element of the array.
0222  *  @param[in] dt      Data type descriptor.  Often retrieved with dtype::get_builtin().
0223  *  @param[in] shape   Shape of the array as STL container of integers; must have begin() and end().
0224  *  @param[in] strides Shape of the array as STL container of integers; must have begin() and end().
0225  *  @param[in] owner   An arbitray Python object that owns that data pointer.  The array object will
0226  *                     keep a reference to the object, and decrement it's reference count when the
0227  *                     array goes out of scope.  Pass None at your own peril.
0228  *
0229  *  This overload takes a const void pointer and sets the "writeable" flag of the array to false.
0230  *
0231  *  @todo Should probably take ranges of iterators rather than actual container objects.
0232  */
0233 template <typename Container>
0234 inline ndarray from_data(void const * data,
0235              dtype const & dt,
0236              Container shape,
0237              Container strides,
0238              python::object const & owner)
0239 {
0240   return numpy::detail::from_data_impl(const_cast<void*>(data), dt, shape, strides, owner, false);
0241 }
0242
0243 /**
0244  *  @brief Transform an arbitrary object into a numpy array with the given requirements.
0245  *
0246  *  @param[in] obj     An arbitrary python object to convert.  Arrays that meet the requirements
0247  *                     will be passed through directly.
0248  *  @param[in] dt      Data type descriptor.  Often retrieved with dtype::get_builtin().
0249  *  @param[in] nd_min  Minimum number of dimensions.
0250  *  @param[in] nd_max  Maximum number of dimensions.
0251  *  @param[in] flags   Bitwise OR of flags specifying additional requirements.
0252  */
0253 BOOST_NUMPY_DECL ndarray from_object(object const & obj,
0254                      dtype const & dt,
0255                      int nd_min,
0256                      int nd_max,
0257                      ndarray::bitflag flags=ndarray::NONE);
0258
0259 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
0260                         dtype const & dt,
0261                         int nd,
0262                         ndarray::bitflag flags=ndarray::NONE)
0263 {
0264   return from_object(obj, dt, nd, nd, flags);
0265 }
0266
0267 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
0268                         dtype const & dt,
0269                         ndarray::bitflag flags=ndarray::NONE)
0270 {
0271   return from_object(obj, dt, 0, 0, flags);
0272 }
0273
0274 BOOST_NUMPY_DECL ndarray from_object(object const & obj,
0275                      int nd_min,
0276                      int nd_max,
0277                      ndarray::bitflag flags=ndarray::NONE);
0278
0279 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
0280                         int nd,
0281                         ndarray::bitflag flags=ndarray::NONE)
0282 {
0283   return from_object(obj, nd, nd, flags);
0284 }
0285
0286 BOOST_NUMPY_DECL inline ndarray from_object(object const & obj,
0287                         ndarray::bitflag flags=ndarray::NONE)
0288 {
0289   return from_object(obj, 0, 0, flags);
0290 }
0291
0292 BOOST_NUMPY_DECL inline ndarray::bitflag operator|(ndarray::bitflag a,
0293                            ndarray::bitflag b)
0294 {
0295   return ndarray::bitflag(int(a) | int(b));
0296 }
0297
0298 BOOST_NUMPY_DECL inline ndarray::bitflag operator&(ndarray::bitflag a,
0299                            ndarray::bitflag b)
0300 {
0301   return ndarray::bitflag(int(a) & int(b));
0302 }
0303
0304 } // namespace boost::python::numpy
0305
0306 namespace converter
0307 {
0308
0309 NUMPY_OBJECT_MANAGER_TRAITS(numpy::ndarray);
0310
0311 }}} // namespace boost::python::converter
0312
0313 #endif