c79706ff4c
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>
51 lines
2.0 KiB
ReStructuredText
51 lines
2.0 KiB
ReStructuredText
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.
|