diff options
author | Andreas Sandberg <andreas.sandberg@arm.com> | 2017-02-27 13:17:51 +0000 |
---|---|---|
committer | Andreas Sandberg <andreas.sandberg@arm.com> | 2017-05-02 12:37:32 +0000 |
commit | c79706ff4ce591df2151db5504d3c224f3c9965f (patch) | |
tree | b56cd2bfe704a40575a71075e78194a4c516c98d /ext/pybind11/docs/advanced/cast/eigen.rst | |
parent | 359cb08623324b62d7c34973ae54d5bc7f23f9fd (diff) | |
download | gem5-c79706ff4ce591df2151db5504d3c224f3c9965f.tar.xz |
ext: Add pybind rev f4b81b3
Change-Id: I52e4fc9ebf2f59da57d8cf8f3e37cc79598c2f5f
Signed-off-by: Andreas Sandberg <andreas.sandberg@arm.com>
Reviewed-by: Andreas Hansson <andreas.hansson@arm.com>
Reviewed-by: Curtis Dunham <curtis.dunham@arm.com>
Reviewed-on: https://gem5-review.googlesource.com/2229
Reviewed-by: Tony Gutierrez <anthony.gutierrez@amd.com>
Reviewed-by: Jason Lowe-Power <jason@lowepower.com>
Reviewed-by: Pierre-Yves PĂ©neau <pierre-yves.peneau@lirmm.fr>
Diffstat (limited to 'ext/pybind11/docs/advanced/cast/eigen.rst')
-rw-r--r-- | ext/pybind11/docs/advanced/cast/eigen.rst | 50 |
1 files changed, 50 insertions, 0 deletions
diff --git a/ext/pybind11/docs/advanced/cast/eigen.rst b/ext/pybind11/docs/advanced/cast/eigen.rst new file mode 100644 index 000000000..b83ca9af9 --- /dev/null +++ b/ext/pybind11/docs/advanced/cast/eigen.rst @@ -0,0 +1,50 @@ +Eigen +===== + +`Eigen <http://eigen.tuxfamily.org>`_ is C++ header-based library for dense and +sparse linear algebra. Due to its popularity and widespread adoption, pybind11 +provides transparent conversion support between Eigen and Scientific Python linear +algebra data types. + +Specifically, when including the optional header file :file:`pybind11/eigen.h`, +pybind11 will automatically and transparently convert + +1. Static and dynamic Eigen dense vectors and matrices to instances of + ``numpy.ndarray`` (and vice versa). + +2. Returned matrix expressions such as blocks (including columns or rows) and + diagonals will be converted to ``numpy.ndarray`` of the expression + values. + +3. Returned matrix-like objects such as Eigen::DiagonalMatrix or + Eigen::SelfAdjointView will be converted to ``numpy.ndarray`` containing the + expressed value. + +4. Eigen sparse vectors and matrices to instances of + ``scipy.sparse.csr_matrix``/``scipy.sparse.csc_matrix`` (and vice versa). + +This makes it possible to bind most kinds of functions that rely on these types. +One major caveat are functions that take Eigen matrices *by reference* and modify +them somehow, in which case the information won't be propagated to the caller. + +.. code-block:: cpp + + /* The Python bindings of these functions won't replicate + the intended effect of modifying the function arguments */ + void scale_by_2(Eigen::Vector3f &v) { + v *= 2; + } + void scale_by_2(Eigen::Ref<Eigen::MatrixXd> &v) { + v *= 2; + } + +To see why this is, refer to the section on :ref:`opaque` (although that +section specifically covers STL data types, the underlying issue is the same). +The :ref:`numpy` sections discuss an efficient alternative for exposing the +underlying native Eigen types as opaque objects in a way that still integrates +with NumPy and SciPy. + +.. seealso:: + + The file :file:`tests/test_eigen.cpp` contains a complete example that + shows how to pass Eigen sparse and dense data types in more detail. |