DOC: use np.copysign() instead of np.sign()

[kalekundert]

The basis vectors returned scipy.linalg.null_space() are guaranteed to be orthonormal, but whether they point in the "positive" or "negative" direction is arbitrary. To remove this source of non-determinism, the 1D documentation example recommends multiplying the basis vector by the sign of its first element.

This seems like good advice, but there's a bug in the way it's implemented. The issue is that np.sign(0) == 0, so if the first element of the basis vector happens to be zero, then the whole vector gets erased. The solution is to use np.copysign(), which doesn't have this behavior (and which even handles -0 correctly).

[mdhaber]

Thanks @kalekundert, that sounds like a helpful fix. To confirm that it's working and ensure that it doesn't get broken again, could you add a unit test to scipy/scipy/linalg/tests/test_decomp.py? I'd move test_null_space into a class called TestNullSpace, then add a new test test_gh19278 (or something descriptive) that would fail in main and pass with this PR. At the top of the test, please add a comment that documents what the test is doing (e.g. paraphrase your top post and explain that the test confirms that this is fixed).

[kalekundert]

I didn't change any code, so I don't think it's possible to write a test that will fail in main and pass on this branch. I also don't see how a new test case would prevent the documentation from breaking again in the future, since the test wouldn't be connected to the docstring in question. Maybe I could change the documentation example such that it triggers the behavior in question, but I think that would detract from the clarity of the example.

[mdhaber]

Oops, I didn't look carefully enough. This is fine as-is. Next time submitting a doc-only change, please include

[skip actions] [skip cirrus]

in the commit message so that only the jobs that build documentation run. The copysign function may be less familiar to users, so it might help to extend the comment about what's going on, but someone can add that later if desired.