ENH: add scipy.linalg.convolution_matrix #11003

mborgerding · 2019-11-02T19:17:20Z

Reference issue
See #7834

What does this implement/fix?

This implements the convolution_matrix function. It is similar to the Matlab/Octave convmtx function but not derived from their implementations in any way.
There is an additional "mode" argument analogous to that in numpy.convolve.

tylerjereddy

Added a few comments.

Note that we normally discuss new features on the mailing list, but I see that this actually already has some positive feedback in the cross-linked issue. The longer-term issue was finding an implementation that was not in another license-restricted code base.

Is there a citation for this implementation?

scipy/linalg/special_matrices.py

scipy/linalg/tests/test_special_matrices.py

scipy/linalg/special_matrices.py

…l coverage

…n the "full" and "valid" modes instead of trimming the "full" result.

ilayn

@mborgerding Thank you for your contribution and time. I've added some comments which all are of minor nature. My only major comment is the function name that it is probably better to spell out instead of the typical matlab cryptic naming scheme. I propose convolution_matrix but maybe you or others have a better name proposal.

scipy/linalg/special_matrices.py

scipy/linalg/tests/test_special_matrices.py

…g comment. test the equality of A[i,j] given in the docstring

…lightly refactored test

mborgerding · 2019-11-05T04:02:26Z

@ilayn , @tylerjereddy
I believe all changes have been done except we have not resolved the discussion above about using itertools.product in a single fast test vs. nesting parameterize decorators to make multiple tests.
I tend to favor the itertools approach as I find it clearer to read and maintain the code, but I don't feel strongly about it. I defer to your judgement.

mborgerding · 2019-11-09T12:56:31Z

bump

ilayn · 2019-11-09T13:07:13Z

Hi @mborgerding instead of range(2,7) for both test cases please use [10, 100] such that at least two order of magnitudes tested. There is not much difference between 3 and 4 in terms of testing behavior. Some problems only reveal themselves when the values are large or arrays size are large.

mborgerding · 2019-11-10T14:00:43Z

Hi @mborgerding instead of range(2,7) for both test cases please use [10, 100] such that at least two order of magnitudes tested. There is not much difference between 3 and 4 in terms of testing behavior. Some problems only reveal themselves when the values are large or arrays size are large.

I expanded the range, but rather than [10,100], it tests the lowest meaningful number for convolution (2) and at least one odd number (9), and 100.

ilayn

You can install pycodestyle and use that for trivial PEP8 checks or adjust your editor such that it does it for you.

scipy/linalg/special_matrices.py

scipy/linalg/tests/test_special_matrices.py

scipy/linalg/special_matrices.py

mborgerding · 2019-11-10T14:57:41Z

You can install pycodestyle and use that for trivial PEP8 checks or adjust your editor such that it does it for you.

I appreciate the tip, but the default pycodestyle options did not seem to catch some of the commas.
Apparently some of the checks are turned off by default.
I was able to turn on full pedantic mode with "--ignore ''"

mborgerding · 2019-11-16T13:03:50Z

Is there anything more to be done for this PR?

scipy/linalg/special_matrices.py

ilayn · 2019-11-16T21:13:54Z

If the CI is green this would be ready for 1.4.0. Please review if you would have time. I'll add the label prospectively.

ilayn · 2019-11-16T21:15:12Z

@mborgerding

Just for the future reference, please make separate branches to work on new features and to send PRs such that your standard working repo does not interfere with the PRs you have submitted. Once a PR is merged you can safely delete that branch and keep working on other branches.

tylerjereddy

Was going to wait for Azure CI to finish to look for coverage holes, but if @ilayn is happy that should be good enough I suppose.

tylerjereddy · 2019-11-16T23:29:15Z

scipy/linalg/tests/test_special_matrices.py

+    def test_vector(n, cpx):
+        'make a complex or real test vector of length n'
+        if cpx:
+            return np.random.normal(size=(n, 2))\


we try to avoid these slash continuations usually -- I guess that can be cleaned up later

I'll be more insistent than @tylerjereddy: don't use a continuation. Fortunately, my next comment will make it unnecessary...

tylerjereddy · 2019-11-16T23:34:42Z

scipy/linalg/tests/test_special_matrices.py

@@ -640,3 +642,45 @@ def test_fiedler_companion():
    fc = fiedler_companion([1., -16., 86., -176., 105.])
    assert_array_almost_equal(eigvals(fc),
                              np.array([7., 5., 3., 1.]))
+
+
+def test_convolution_matrix():


normally we'd use a class and then place specific tests within that class for pytest namespace resolution

It's a singleton so here a class is not needed

I don't understand--there are actually several things being tested below--normally one would split each thing being tested into its own specific unit test classified within the same test class.

I agree with @tylerjereddy, the tests should be split up, and the big loop at the end should use pytest's parametrize feature. The increased granularity lets us know all the things that are going wrong if there is a failure, instead of just the first thing that goes wrong.

tylerjereddy · 2019-11-16T23:41:07Z

scipy/linalg/tests/test_special_matrices.py

+        convolution_matrix((1, 1), 4, mode='invalid argument')
+
+    array_sizes = (2, 9, 100)
+    for cpx, na, nv, mode in itertools.product(


I suppose this is still used in our codebase a fair bit; at some number of permutations I think we should prefer to parametrize, but anyway..

tylerjereddy · 2019-11-17T00:16:27Z

@rgommers Have you observed this Python 3.8/Windows Azure timeout issue before?

tylerjereddy · 2019-11-17T00:17:57Z

The ppc64le failure probably isn't related

tylerjereddy · 2019-11-17T00:30:59Z

There are no holes in the line coverage, which is good.

rgommers · 2019-11-17T01:55:55Z

@rgommers Have you observed this Python 3.8/Windows Azure timeout issue before?

no I haven't

tylerjereddy · 2019-11-17T03:44:13Z

I'm bumping the milestone--we've already had more last-minute merges than I'd like & the CI is a little strange here, but this looks close to merging after we branch.

ilayn · 2019-11-17T07:34:28Z

The failures are not related to this PR.

tylerjereddy · 2019-11-17T17:33:09Z

scipy/linalg/tests/test_special_matrices.py

+            return np.random.normal(size=(n,))
+
+    # first arg must be a 1d array, otherwise ValueError
+    with assert_raises(ValueError):


This is one test

tylerjereddy · 2019-11-17T17:33:22Z

scipy/linalg/tests/test_special_matrices.py

+        convolution_matrix(1, 4)
+
+    # mode must be in ('full','valid','same')
+    with assert_raises(ValueError):


This is testing something else

That's unnecessary granularity. And also if there is no scope nesting it's just a preference. If we write one test per assertion we will have millions of tests.

See examples in the rest of the file for more examples.

Unfortunately, there is a lot of code in our codebase that does not conform to what we now consider best practices. It is our job as reviewers to ensure the new code does so.

WarrenWeckesser

@mborgerding, thanks for contributing this pull request. convolution_matrix will be a nice addtion to the collection of special matrix functions, and I'd like to get it into version 1.5.0.

I made a bunch of comments in-line. Here are some additional comments:

Thanks for completing the table of special matrices in the tutorial!

There are some incorrect results.
In the following two examples, the output should be 3*np.eye(5):

In [114]: convolution_matrix([3], 5, mode='valid')

Out[114]: array([], shape=(0, 0), dtype=int64)

In [115]: convolution_matrix([3], 5, mode='same')

Out[115]: array([], shape=(0, 5), dtype=int64)

In the next two examples, the output should be np.array([[3], [4]]):

In [146]: convolution_matrix([3, 4], 1, mode='valid')

Out[146]: array([], shape=(0, 0), dtype=int64)

In [147]: convolution_matrix([3, 4], 1, mode='same')

Out[147]: array([], shape=(0, 1), dtype=int64)

It has been about 5 months since there was activity in this pull request. Do you still have time and interest for working on it? Let us know. If not, we can take it over.

WarrenWeckesser · 2020-05-02T05:32:41Z

scipy/linalg/special_matrices.py

+    """
+    Construct a convolution matrix.
+
+    Constructs the dense matrix representing convolution[1].


Need a trailing _ for the citation.

Suggested change

Constructs the dense matrix representing convolution[1].

Constructs the dense matrix representing convolution[1]_.

WarrenWeckesser · 2020-05-02T05:33:18Z

scipy/linalg/special_matrices.py

+    ``A = convolution_matrix(a, n[, mode])`` creates a matrix ``A`` such that
+    ``A @ v`` (or ``matmul(A, v)``) is equivalent to using
+    ``convolve(a, v[, mode])``. In the default 'full' mode, the entries of
+    ``A`` is given by ``A[i,j] == (a[i-j] if (0 <= (i-j) < m) else 0)``.


Suggested change

``A`` is given by ``A[i,j] == (a[i-j] if (0 <= (i-j) < m) else 0)``.

``A`` are given by ``A[i,j] == (a[i-j] if (0 <= (i-j) < m) else 0)``.

WarrenWeckesser · 2020-05-02T05:33:52Z

scipy/linalg/special_matrices.py

+        The 1-D array to convolve.
+    n : int
+        The number of columns in the resulting matrix.
+        This is analogous to the length of `v` in ``numpy.convolve(a,v)``


Suggested change

This is analogous to the length of `v` in ``numpy.convolve(a,v)``

This is analogous to the length of `v` in ``numpy.convolve(a,v)``.

WarrenWeckesser · 2020-05-02T05:34:20Z

scipy/linalg/special_matrices.py

+        This is analogous to the length of `v` in ``numpy.convolve(a,v)``
+    mode : str
+        This is analogous to `mode` in numpy.convolve(v, a, mode).
+        It must be one of ('full','valid','same').


Spaces after commas:

Suggested change

It must be one of ('full','valid','same').

It must be one of ('full', 'valid', 'same').

WarrenWeckesser · 2020-05-02T05:35:05Z

scipy/linalg/special_matrices.py

+    Returns
+    -------
+    A : (k, n) ndarray
+        The convolution matrix whose row count `k` depends on `mode`


Might need :: at the end?

Suggested change

The convolution matrix whose row count `k` depends on `mode`

The convolution matrix whose row count `k` depends on `mode`::

WarrenWeckesser · 2020-05-02T05:36:11Z

scipy/linalg/special_matrices.py

+           [ 0, -1,  2, -1,  0],
+           [ 0,  0, -1,  2, -1],
+           [ 0,  0,  0, -1,  2]])
+


Let's add examples for mode='full' and mode='valid', too.

WarrenWeckesser · 2020-05-02T05:37:37Z

scipy/linalg/special_matrices.py

+
+    if mode not in ('full', 'valid', 'same'):
+        raise ValueError(
+            "'mode' argument must be one of ('full','valid','same')")


Spaces after commas:

Suggested change

"'mode' argument must be one of ('full','valid','same')")

"'mode' argument must be one of ('full', 'valid', 'same')")

WarrenWeckesser · 2020-05-02T05:45:18Z

scipy/linalg/tests/test_special_matrices.py

+    def test_vector(n, cpx):
+        'make a complex or real test vector of length n'
+        if cpx:
+            return np.random.normal(size=(n, 2))\


I'll be more insistent than @tylerjereddy: don't use a continuation. Fortunately, my next comment will make it unnecessary...

WarrenWeckesser · 2020-05-02T05:46:49Z

scipy/linalg/tests/test_special_matrices.py

+        'make a complex or real test vector of length n'
+        if cpx:
+            return np.random.normal(size=(n, 2))\
+                .astype(np.float64).view(np.complex128).ravel()


There is no need for .astype(np.float64) here. That is already the return type of np.random.normal().

Suggested change

.astype(np.float64).view(np.complex128).ravel()

.view(np.complex128).ravel()

WarrenWeckesser · 2020-05-02T05:52:58Z

scipy/linalg/tests/test_special_matrices.py

+            A = convolution_matrix(a, nv, mode)
+        y2 = A @ v
+        assert_array_almost_equal(y1, y2)
+        if mode == 'full':


The nested loop in this if statement makes this part of the test very slow. It is checking element by element that A is a Toeplitz matrix containing a in the expected positions. I think we can simply delete this part of the test. If A is not the correct Toeplitz matrix, the probability of the previous comparison of y1 and y2 passing is miniscule.

tylerjereddy · 2020-05-16T23:36:13Z

Do you still have time and interest for working on it? Let us know. If not, we can take it over.

@WarrenWeckesser Are you going to have time to take over here before we branch?

WarrenWeckesser · 2020-05-16T23:43:18Z

@tylerjereddy, thanks for the reminder. Yes, I'll take this over.

WarrenWeckesser · 2020-05-17T02:14:29Z

Updated pull request is in #12135.

WarrenWeckesser · 2020-05-20T17:40:38Z

This PR was continued in gh-12135, and that PR has been merged, so closing.

Thanks @mborgerding for the contribution, and thanks @ilayn and @tylerjereddy for the reviews.

Mark Borgerding added 3 commits November 2, 2019 15:02

added convmtx and test_convmtx

21fbe5b

added versionadded (per setup.py )

d85b277

minor reformatting:PEP8 spaces after commas

21efb54

mborgerding changed the title ~~add convmtx to scipy.linalg~~ ENH: add convmtx to scipy.linalg Nov 2, 2019

made docstring suitable for sphinx

1e5596b

tylerjereddy added enhancement A new feature or improvement scipy.linalg labels Nov 2, 2019

tylerjereddy reviewed Nov 2, 2019

View reviewed changes

Mark Borgerding added 2 commits November 3, 2019 09:31

improved convmtx docstring. added test to raise exception and get ful…

8f816de

…l coverage

made convmtx more efficient. It now constructs the minimal 2d array i…

83ed6a3

…n the "full" and "valid" modes instead of trimming the "full" result.

ilayn requested changes Nov 3, 2019

View reviewed changes

Mark Borgerding added 5 commits November 3, 2019 11:30

cleaner to use pytest.raises context manager to check for exceptions

1456a4c

added matmul operator and improved parameter descriptions to docstrin…

b2c4c99

…g comment. test the equality of A[i,j] given in the docstring

changed convmtx to more descriptive convolution_matrix

7bea8a5

convolution_matrix: restricted mode to valid strings. Clarified and s…

2a1bd97

…lightly refactored test

PEP8 reformatting

10c8fe0

mborgerding changed the title ~~ENH: add convmtx to scipy.linalg~~ ENH: add scipy.linalg.convolution_matrix Nov 5, 2019

Mark Borgerding added 2 commits November 9, 2019 12:49

test_convolution_matrix: bigger range of test sizes (fewer actual tests)

bac3477

Merge remote-tracking branch 'origin/master'

877d18c

ilayn requested changes Nov 10, 2019

View reviewed changes

changes made by : autopep8 --ignore '' -i ...

e50d282

Mark Borgerding and others added 2 commits November 10, 2019 16:40

use double backticks for code in docstrings

36b79b3

Merge remote-tracking branch 'scipy/master'

b936d29

ilayn requested changes Nov 16, 2019

View reviewed changes

scipy/linalg/special_matrices.py Outdated Show resolved Hide resolved

DOC: A PEP8 typo and tutorial pages update

435e362

ilayn added this to the 1.4.0 milestone Nov 16, 2019

ilayn approved these changes Nov 16, 2019

View reviewed changes

tylerjereddy reviewed Nov 16, 2019

View reviewed changes

tylerjereddy modified the milestones: 1.4.0, 1.5.0 Nov 17, 2019

tylerjereddy reviewed Nov 17, 2019

View reviewed changes

WarrenWeckesser requested changes May 2, 2020

View reviewed changes

WarrenWeckesser mentioned this pull request May 17, 2020

ENH: linalg: Add the function convolution_matrix. #12135

Merged

WarrenWeckesser closed this May 20, 2020

ilayn mentioned this pull request Apr 20, 2021

Stopping taking away credit from small contributors #13904

Closed

	Constructs the dense matrix representing convolution[1].
	Constructs the dense matrix representing convolution[1]_.

	``A`` is given by ``A[i,j] == (a[i-j] if (0 <= (i-j) < m) else 0)``.
	``A`` are given by ``A[i,j] == (a[i-j] if (0 <= (i-j) < m) else 0)``.

	This is analogous to the length of `v` in ``numpy.convolve(a,v)``
	This is analogous to the length of `v` in ``numpy.convolve(a,v)``.

	It must be one of ('full','valid','same').
	It must be one of ('full', 'valid', 'same').

	The convolution matrix whose row count `k` depends on `mode`
	The convolution matrix whose row count `k` depends on `mode`::

	"'mode' argument must be one of ('full','valid','same')")
	"'mode' argument must be one of ('full', 'valid', 'same')")

	.astype(np.float64).view(np.complex128).ravel()
	.view(np.complex128).ravel()

Uh oh!

ENH: add scipy.linalg.convolution_matrix #11003

ENH: add scipy.linalg.convolution_matrix #11003

Uh oh!

Conversation

mborgerding commented Nov 2, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this implement/fix?

Uh oh!

tylerjereddy left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ilayn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mborgerding commented Nov 5, 2019

Uh oh!

mborgerding commented Nov 9, 2019

Uh oh!

ilayn commented Nov 9, 2019

Uh oh!

mborgerding commented Nov 10, 2019

Uh oh!

ilayn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mborgerding commented Nov 10, 2019

Uh oh!

mborgerding commented Nov 16, 2019

Uh oh!

Uh oh!

ilayn commented Nov 16, 2019

Uh oh!

ilayn commented Nov 16, 2019

Uh oh!

tylerjereddy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylerjereddy commented Nov 17, 2019

Uh oh!

tylerjereddy commented Nov 17, 2019

Uh oh!

tylerjereddy commented Nov 17, 2019

Uh oh!

rgommers commented Nov 17, 2019

mborgerding commented Nov 2, 2019 •

edited

Loading

tylerjereddy left a comment •

edited

Loading

WarrenWeckesser May 2, 2020 •

edited

Loading