EigenΒΆ
Eigen 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 pybind11/eigen.h
,
pybind11 will automatically and transparently convert
- Static and dynamic Eigen dense vectors and matrices to instances of
numpy.ndarray
(and vice versa). - Returned matrix expressions such as blocks (including columns or rows) and
diagonals will be converted to
numpy.ndarray
of the expression values. - Returned matrix-like objects such as Eigen::DiagonalMatrix or
Eigen::SelfAdjointView will be converted to
numpy.ndarray
containing the expressed value. - 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.
/* 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 Making opaque types (although that section specifically covers STL data types, the underlying issue is the same). The 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.
See also
The file tests/test_eigen.cpp
contains a complete example that
shows how to pass Eigen sparse and dense data types in more detail.