123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438 |
- .. _numpy:
- NumPy
- #####
- Buffer protocol
- ===============
- Python supports an extremely general and convenient approach for exchanging
- data between plugin libraries. Types can expose a buffer view [#f2]_, which
- provides fast direct access to the raw internal data representation. Suppose we
- want to bind the following simplistic Matrix class:
- .. code-block:: cpp
- class Matrix {
- public:
- Matrix(size_t rows, size_t cols) : m_rows(rows), m_cols(cols) {
- m_data = new float[rows*cols];
- }
- float *data() { return m_data; }
- size_t rows() const { return m_rows; }
- size_t cols() const { return m_cols; }
- private:
- size_t m_rows, m_cols;
- float *m_data;
- };
- The following binding code exposes the ``Matrix`` contents as a buffer object,
- making it possible to cast Matrices into NumPy arrays. It is even possible to
- completely avoid copy operations with Python expressions like
- ``np.array(matrix_instance, copy = False)``.
- .. code-block:: cpp
- py::class_<Matrix>(m, "Matrix", py::buffer_protocol())
- .def_buffer([](Matrix &m) -> py::buffer_info {
- return py::buffer_info(
- m.data(), /* Pointer to buffer */
- sizeof(float), /* Size of one scalar */
- py::format_descriptor<float>::format(), /* Python struct-style format descriptor */
- 2, /* Number of dimensions */
- { m.rows(), m.cols() }, /* Buffer dimensions */
- { sizeof(float) * m.cols(), /* Strides (in bytes) for each index */
- sizeof(float) }
- );
- });
- Supporting the buffer protocol in a new type involves specifying the special
- ``py::buffer_protocol()`` tag in the ``py::class_`` constructor and calling the
- ``def_buffer()`` method with a lambda function that creates a
- ``py::buffer_info`` description record on demand describing a given matrix
- instance. The contents of ``py::buffer_info`` mirror the Python buffer protocol
- specification.
- .. code-block:: cpp
- struct buffer_info {
- void *ptr;
- py::ssize_t itemsize;
- std::string format;
- py::ssize_t ndim;
- std::vector<py::ssize_t> shape;
- std::vector<py::ssize_t> strides;
- };
- To create a C++ function that can take a Python buffer object as an argument,
- simply use the type ``py::buffer`` as one of its arguments. Buffers can exist
- in a great variety of configurations, hence some safety checks are usually
- necessary in the function body. Below, you can see a basic example on how to
- define a custom constructor for the Eigen double precision matrix
- (``Eigen::MatrixXd``) type, which supports initialization from compatible
- buffer objects (e.g. a NumPy matrix).
- .. code-block:: cpp
- /* Bind MatrixXd (or some other Eigen type) to Python */
- typedef Eigen::MatrixXd Matrix;
- typedef Matrix::Scalar Scalar;
- constexpr bool rowMajor = Matrix::Flags & Eigen::RowMajorBit;
- py::class_<Matrix>(m, "Matrix", py::buffer_protocol())
- .def(py::init([](py::buffer b) {
- typedef Eigen::Stride<Eigen::Dynamic, Eigen::Dynamic> Strides;
- /* Request a buffer descriptor from Python */
- py::buffer_info info = b.request();
- /* Some sanity checks ... */
- if (info.format != py::format_descriptor<Scalar>::format())
- throw std::runtime_error("Incompatible format: expected a double array!");
- if (info.ndim != 2)
- throw std::runtime_error("Incompatible buffer dimension!");
- auto strides = Strides(
- info.strides[rowMajor ? 0 : 1] / (py::ssize_t)sizeof(Scalar),
- info.strides[rowMajor ? 1 : 0] / (py::ssize_t)sizeof(Scalar));
- auto map = Eigen::Map<Matrix, 0, Strides>(
- static_cast<Scalar *>(info.ptr), info.shape[0], info.shape[1], strides);
- return Matrix(map);
- }));
- For reference, the ``def_buffer()`` call for this Eigen data type should look
- as follows:
- .. code-block:: cpp
- .def_buffer([](Matrix &m) -> py::buffer_info {
- return py::buffer_info(
- m.data(), /* Pointer to buffer */
- sizeof(Scalar), /* Size of one scalar */
- py::format_descriptor<Scalar>::format(), /* Python struct-style format descriptor */
- 2, /* Number of dimensions */
- { m.rows(), m.cols() }, /* Buffer dimensions */
- { sizeof(Scalar) * (rowMajor ? m.cols() : 1),
- sizeof(Scalar) * (rowMajor ? 1 : m.rows()) }
- /* Strides (in bytes) for each index */
- );
- })
- For a much easier approach of binding Eigen types (although with some
- limitations), refer to the section on :doc:`/advanced/cast/eigen`.
- .. seealso::
- The file :file:`tests/test_buffers.cpp` contains a complete example
- that demonstrates using the buffer protocol with pybind11 in more detail.
- .. [#f2] http://docs.python.org/3/c-api/buffer.html
- Arrays
- ======
- By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can
- restrict the function so that it only accepts NumPy arrays (rather than any
- type of Python object satisfying the buffer protocol).
- In many situations, we want to define a function which only accepts a NumPy
- array of a certain data type. This is possible via the ``py::array_t<T>``
- template. For instance, the following function requires the argument to be a
- NumPy array containing double precision values.
- .. code-block:: cpp
- void f(py::array_t<double> array);
- When it is invoked with a different type (e.g. an integer or a list of
- integers), the binding code will attempt to cast the input into a NumPy array
- of the requested type. This feature requires the :file:`pybind11/numpy.h`
- header to be included. Note that :file:`pybind11/numpy.h` does not depend on
- the NumPy headers, and thus can be used without declaring a build-time
- dependency on NumPy; NumPy>=1.7.0 is a runtime dependency.
- Data in NumPy arrays is not guaranteed to packed in a dense manner;
- furthermore, entries can be separated by arbitrary column and row strides.
- Sometimes, it can be useful to require a function to only accept dense arrays
- using either the C (row-major) or Fortran (column-major) ordering. This can be
- accomplished via a second template argument with values ``py::array::c_style``
- or ``py::array::f_style``.
- .. code-block:: cpp
- void f(py::array_t<double, py::array::c_style | py::array::forcecast> array);
- The ``py::array::forcecast`` argument is the default value of the second
- template parameter, and it ensures that non-conforming arguments are converted
- into an array satisfying the specified requirements instead of trying the next
- function overload.
- Structured types
- ================
- In order for ``py::array_t`` to work with structured (record) types, we first
- need to register the memory layout of the type. This can be done via
- ``PYBIND11_NUMPY_DTYPE`` macro, called in the plugin definition code, which
- expects the type followed by field names:
- .. code-block:: cpp
- struct A {
- int x;
- double y;
- };
- struct B {
- int z;
- A a;
- };
- // ...
- PYBIND11_MODULE(test, m) {
- // ...
- PYBIND11_NUMPY_DTYPE(A, x, y);
- PYBIND11_NUMPY_DTYPE(B, z, a);
- /* now both A and B can be used as template arguments to py::array_t */
- }
- The structure should consist of fundamental arithmetic types, ``std::complex``,
- previously registered substructures, and arrays of any of the above. Both C++
- arrays and ``std::array`` are supported. While there is a static assertion to
- prevent many types of unsupported structures, it is still the user's
- responsibility to use only "plain" structures that can be safely manipulated as
- raw memory without violating invariants.
- Vectorizing functions
- =====================
- Suppose we want to bind a function with the following signature to Python so
- that it can process arbitrary NumPy array arguments (vectors, matrices, general
- N-D arrays) in addition to its normal arguments:
- .. code-block:: cpp
- double my_func(int x, float y, double z);
- After including the ``pybind11/numpy.h`` header, this is extremely simple:
- .. code-block:: cpp
- m.def("vectorized_func", py::vectorize(my_func));
- Invoking the function like below causes 4 calls to be made to ``my_func`` with
- each of the array elements. The significant advantage of this compared to
- solutions like ``numpy.vectorize()`` is that the loop over the elements runs
- entirely on the C++ side and can be crunched down into a tight, optimized loop
- by the compiler. The result is returned as a NumPy array of type
- ``numpy.dtype.float64``.
- .. code-block:: pycon
- >>> x = np.array([[1, 3],[5, 7]])
- >>> y = np.array([[2, 4],[6, 8]])
- >>> z = 3
- >>> result = vectorized_func(x, y, z)
- The scalar argument ``z`` is transparently replicated 4 times. The input
- arrays ``x`` and ``y`` are automatically converted into the right types (they
- are of type ``numpy.dtype.int64`` but need to be ``numpy.dtype.int32`` and
- ``numpy.dtype.float32``, respectively).
- .. note::
- Only arithmetic, complex, and POD types passed by value or by ``const &``
- reference are vectorized; all other arguments are passed through as-is.
- Functions taking rvalue reference arguments cannot be vectorized.
- In cases where the computation is too complicated to be reduced to
- ``vectorize``, it will be necessary to create and access the buffer contents
- manually. The following snippet contains a complete example that shows how this
- works (the code is somewhat contrived, since it could have been done more
- simply using ``vectorize``).
- .. code-block:: cpp
- #include <pybind11/pybind11.h>
- #include <pybind11/numpy.h>
- namespace py = pybind11;
- py::array_t<double> add_arrays(py::array_t<double> input1, py::array_t<double> input2) {
- py::buffer_info buf1 = input1.request(), buf2 = input2.request();
- if (buf1.ndim != 1 || buf2.ndim != 1)
- throw std::runtime_error("Number of dimensions must be one");
- if (buf1.size != buf2.size)
- throw std::runtime_error("Input shapes must match");
- /* No pointer is passed, so NumPy will allocate the buffer */
- auto result = py::array_t<double>(buf1.size);
- py::buffer_info buf3 = result.request();
- double *ptr1 = static_cast<double *>(buf1.ptr);
- double *ptr2 = static_cast<double *>(buf2.ptr);
- double *ptr3 = static_cast<double *>(buf3.ptr);
- for (size_t idx = 0; idx < buf1.shape[0]; idx++)
- ptr3[idx] = ptr1[idx] + ptr2[idx];
- return result;
- }
- PYBIND11_MODULE(test, m) {
- m.def("add_arrays", &add_arrays, "Add two NumPy arrays");
- }
- .. seealso::
- The file :file:`tests/test_numpy_vectorize.cpp` contains a complete
- example that demonstrates using :func:`vectorize` in more detail.
- Direct access
- =============
- For performance reasons, particularly when dealing with very large arrays, it
- is often desirable to directly access array elements without internal checking
- of dimensions and bounds on every access when indices are known to be already
- valid. To avoid such checks, the ``array`` class and ``array_t<T>`` template
- class offer an unchecked proxy object that can be used for this unchecked
- access through the ``unchecked<N>`` and ``mutable_unchecked<N>`` methods,
- where ``N`` gives the required dimensionality of the array:
- .. code-block:: cpp
- m.def("sum_3d", [](py::array_t<double> x) {
- auto r = x.unchecked<3>(); // x must have ndim = 3; can be non-writeable
- double sum = 0;
- for (py::ssize_t i = 0; i < r.shape(0); i++)
- for (py::ssize_t j = 0; j < r.shape(1); j++)
- for (py::ssize_t k = 0; k < r.shape(2); k++)
- sum += r(i, j, k);
- return sum;
- });
- m.def("increment_3d", [](py::array_t<double> x) {
- auto r = x.mutable_unchecked<3>(); // Will throw if ndim != 3 or flags.writeable is false
- for (py::ssize_t i = 0; i < r.shape(0); i++)
- for (py::ssize_t j = 0; j < r.shape(1); j++)
- for (py::ssize_t k = 0; k < r.shape(2); k++)
- r(i, j, k) += 1.0;
- }, py::arg().noconvert());
- To obtain the proxy from an ``array`` object, you must specify both the data
- type and number of dimensions as template arguments, such as ``auto r =
- myarray.mutable_unchecked<float, 2>()``.
- If the number of dimensions is not known at compile time, you can omit the
- dimensions template parameter (i.e. calling ``arr_t.unchecked()`` or
- ``arr.unchecked<T>()``. This will give you a proxy object that works in the
- same way, but results in less optimizable code and thus a small efficiency
- loss in tight loops.
- Note that the returned proxy object directly references the array's data, and
- only reads its shape, strides, and writeable flag when constructed. You must
- take care to ensure that the referenced array is not destroyed or reshaped for
- the duration of the returned object, typically by limiting the scope of the
- returned instance.
- The returned proxy object supports some of the same methods as ``py::array`` so
- that it can be used as a drop-in replacement for some existing, index-checked
- uses of ``py::array``:
- - ``r.ndim()`` returns the number of dimensions
- - ``r.data(1, 2, ...)`` and ``r.mutable_data(1, 2, ...)``` returns a pointer to
- the ``const T`` or ``T`` data, respectively, at the given indices. The
- latter is only available to proxies obtained via ``a.mutable_unchecked()``.
- - ``itemsize()`` returns the size of an item in bytes, i.e. ``sizeof(T)``.
- - ``ndim()`` returns the number of dimensions.
- - ``shape(n)`` returns the size of dimension ``n``
- - ``size()`` returns the total number of elements (i.e. the product of the shapes).
- - ``nbytes()`` returns the number of bytes used by the referenced elements
- (i.e. ``itemsize()`` times ``size()``).
- .. seealso::
- The file :file:`tests/test_numpy_array.cpp` contains additional examples
- demonstrating the use of this feature.
- Ellipsis
- ========
- Python 3 provides a convenient ``...`` ellipsis notation that is often used to
- slice multidimensional arrays. For instance, the following snippet extracts the
- middle dimensions of a tensor with the first and last index set to zero.
- In Python 2, the syntactic sugar ``...`` is not available, but the singleton
- ``Ellipsis`` (of type ``ellipsis``) can still be used directly.
- .. code-block:: python
- a = # a NumPy array
- b = a[0, ..., 0]
- The function ``py::ellipsis()`` function can be used to perform the same
- operation on the C++ side:
- .. code-block:: cpp
- py::array a = /* A NumPy array */;
- py::array b = a[py::make_tuple(0, py::ellipsis(), 0)];
- .. versionchanged:: 2.6
- ``py::ellipsis()`` is now also avaliable in Python 2.
- Memory view
- ===========
- For a case when we simply want to provide a direct accessor to C/C++ buffer
- without a concrete class object, we can return a ``memoryview`` object. Suppose
- we wish to expose a ``memoryview`` for 2x4 uint8_t array, we can do the
- following:
- .. code-block:: cpp
- const uint8_t buffer[] = {
- 0, 1, 2, 3,
- 4, 5, 6, 7
- };
- m.def("get_memoryview2d", []() {
- return py::memoryview::from_buffer(
- buffer, // buffer pointer
- { 2, 4 }, // shape (rows, cols)
- { sizeof(uint8_t) * 4, sizeof(uint8_t) } // strides in bytes
- );
- })
- This approach is meant for providing a ``memoryview`` for a C/C++ buffer not
- managed by Python. The user is responsible for managing the lifetime of the
- buffer. Using a ``memoryview`` created in this way after deleting the buffer in
- C++ side results in undefined behavior.
- We can also use ``memoryview::from_memory`` for a simple 1D contiguous buffer:
- .. code-block:: cpp
- m.def("get_memoryview1d", []() {
- return py::memoryview::from_memory(
- buffer, // buffer pointer
- sizeof(uint8_t) * 8 // buffer size
- );
- })
- .. note::
- ``memoryview::from_memory`` is not available in Python 2.
- .. versionchanged:: 2.6
- ``memoryview::from_memory`` added.
|