pybind / pybind/pybind11

eigen: Return type "annotation" does not reflect actual shape for vectors?

Open
#2,400 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
18k
Forks
2.3k
Avg merge
5d 17h
Merged PRs (30d)
10

Description

Issue description

Per docs here (as of 2.5.0):
https://pybind11.readthedocs.io/en/stable/advanced/cast/eigen.html#vectors-versus-column-row-matrices

When returning an Eigen vector to numpy, [...] if it is a compile-time vector–that is, the type has either the number of rows or columns set to 1 at compile time–pybind11 converts to a 1D numpy array when returning the value. [...]

Makes total sense. However, looking at the docstrings:
https://github.com/pybind/pybind11/blob/4d9024ec71f30223fc161b7a01fcc486abce800b/tests/test_eigen.py#L609-L623

For m.double_col, the input type makes sense, because that matters to C++ (as mentioned in the docs).

However, the return type is a bit misleading: it states that the output types is numpy.ndarray[numpy.float32[m, 1]].

This is a bit misleading, because the return type's shape is actually (m,).
Additionally, when the return type has

This bit us in https://github.com/RobotLocomotion/drake/issues/13885.
The docs do have a suggested workaround, which is what we'll do, but it'd be nice if the annotation were a bit more truthful.

Reproducible example code

See aforementioned example.

Possible solutions

  1. Somehow distinguish the type string based on return-type? (that could be down by "rerouting" the return type somehow?)
  2. Discard shape information (at the cost of sacrificing info in the argument - probably a non-starter)
  3. As-is
  4. Other?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Eigen vector-versus-column-row-matrix documentation and the referenced section of tests/test_eigen.py around lines 609-623, especially the double_col docstring. Reproduce the mismatch between the return annotation and the actual NumPy shape, then determine which proposed behavior is appropriate and verify the resulting annotation against the example.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.