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>

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.