Python GenericMatrix.set docstring misleading
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
DOLFIN |
New
|
Undecided
|
Unassigned |
Bug Description
We have a dolfin.cpp.Matrix called foo. The documentation for its set function:
-------
In [349]: foo.set?
Type: instancemethod
Base Class: <type 'instancemethod'>
String Form: <bound method Matrix.
Namespace: Interactive
Docstring:
**Overloaded versions**
* set\ (block, num_rows, rows)
Set block of values
* set\ (block, m, rows, n, cols)
Set block of values
-------
First, there seems to be no way to invoke the function in the second way: an error is always received about 4 arguments being expected, but 6 supplied.
Secondly, the parameter description 'block, num_rows, rows' is misleading. The role of these arguments appears to be 'target_rows' resp. 'target_cols'.
Example:
-------
In [350]: foo=Matrix(E)
In [351]: foo.zero()
In [352]: foo.set(
In [353]: foo.apply('add')
In [354]: foo.array()
Out[354]:
array([[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 42., 43., 44., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 45., 46., 47., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],
[ 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.]])
-------
This is because we automatically generate documentation based on the C++ interface. Here you are actually invoking the last set version, but instead of 5 (or 6 as Python add self) arguments it expects 3, as m and rows, and n and cols are lumped together into one NumPy array argument.
In addition are the autogenerated documentation not taking into account that the first version is really not included in the swig interface, as it is %ignored.
These errors are difficult to fix. I have registered a new bug which more precisely describe the problem.