eigen.rst revision 11986
17375Sgblack@eecs.umich.eduEigen 27375Sgblack@eecs.umich.edu===== 37375Sgblack@eecs.umich.edu 47375Sgblack@eecs.umich.edu`Eigen <http://eigen.tuxfamily.org>`_ is C++ header-based library for dense and 57375Sgblack@eecs.umich.edusparse linear algebra. Due to its popularity and widespread adoption, pybind11 67375Sgblack@eecs.umich.eduprovides transparent conversion support between Eigen and Scientific Python linear 77375Sgblack@eecs.umich.edualgebra data types. 87375Sgblack@eecs.umich.edu 97375Sgblack@eecs.umich.eduSpecifically, when including the optional header file :file:`pybind11/eigen.h`, 107375Sgblack@eecs.umich.edupybind11 will automatically and transparently convert 117375Sgblack@eecs.umich.edu 127375Sgblack@eecs.umich.edu1. Static and dynamic Eigen dense vectors and matrices to instances of 137375Sgblack@eecs.umich.edu ``numpy.ndarray`` (and vice versa). 147375Sgblack@eecs.umich.edu 157375Sgblack@eecs.umich.edu2. Returned matrix expressions such as blocks (including columns or rows) and 167375Sgblack@eecs.umich.edu diagonals will be converted to ``numpy.ndarray`` of the expression 177375Sgblack@eecs.umich.edu values. 187375Sgblack@eecs.umich.edu 197375Sgblack@eecs.umich.edu3. Returned matrix-like objects such as Eigen::DiagonalMatrix or 207375Sgblack@eecs.umich.edu Eigen::SelfAdjointView will be converted to ``numpy.ndarray`` containing the 217375Sgblack@eecs.umich.edu expressed value. 227375Sgblack@eecs.umich.edu 237375Sgblack@eecs.umich.edu4. Eigen sparse vectors and matrices to instances of 247375Sgblack@eecs.umich.edu ``scipy.sparse.csr_matrix``/``scipy.sparse.csc_matrix`` (and vice versa). 257375Sgblack@eecs.umich.edu 267375Sgblack@eecs.umich.eduThis makes it possible to bind most kinds of functions that rely on these types. 277375Sgblack@eecs.umich.eduOne major caveat are functions that take Eigen matrices *by reference* and modify 287375Sgblack@eecs.umich.eduthem somehow, in which case the information won't be propagated to the caller. 297375Sgblack@eecs.umich.edu 307375Sgblack@eecs.umich.edu.. code-block:: cpp 317375Sgblack@eecs.umich.edu 327375Sgblack@eecs.umich.edu /* The Python bindings of these functions won't replicate 337375Sgblack@eecs.umich.edu the intended effect of modifying the function arguments */ 347375Sgblack@eecs.umich.edu void scale_by_2(Eigen::Vector3f &v) { 357375Sgblack@eecs.umich.edu v *= 2; 367375Sgblack@eecs.umich.edu } 377375Sgblack@eecs.umich.edu void scale_by_2(Eigen::Ref<Eigen::MatrixXd> &v) { 387375Sgblack@eecs.umich.edu v *= 2; 397375Sgblack@eecs.umich.edu } 407640Sgblack@eecs.umich.edu 417640Sgblack@eecs.umich.eduTo see why this is, refer to the section on :ref:`opaque` (although that 427640Sgblack@eecs.umich.edusection specifically covers STL data types, the underlying issue is the same). 437640Sgblack@eecs.umich.eduThe :ref:`numpy` sections discuss an efficient alternative for exposing the 447640Sgblack@eecs.umich.eduunderlying native Eigen types as opaque objects in a way that still integrates 457640Sgblack@eecs.umich.eduwith NumPy and SciPy. 467644Sali.saidi@arm.com 477640Sgblack@eecs.umich.edu.. seealso:: 487644Sali.saidi@arm.com 497644Sali.saidi@arm.com The file :file:`tests/test_eigen.cpp` contains a complete example that 507644Sali.saidi@arm.com shows how to pass Eigen sparse and dense data types in more detail. 517644Sali.saidi@arm.com