DOC: optimize: nnls documents atol parameter which does nothing

[nickodell]

Issue with current documentation:

This is the current documentation for the atol parameter:

Tolerance value used in the algorithm to assess closeness to zero in the projected residual (A.T @ (A x - b) entries. Increasing this value relaxes the solution constraints. A typical relaxation value can be selected as max(m, n) * np.linalg.norm(a, 1) * np.spacing(1.). This value is not set as default since the norm operation becomes expensive for large problems hence can be used only when necessary.

https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.nnls.html

I think this is confusing for a few reasons:

1. It doesn't document what the default value is - it documents what the default value is not.
2. It's too concerned with implementation details. The documentation should be phrased in terms of actionable steps the user can take to solve their problem.

Idea or request for content:

Here's the phrasing I would suggest to fix these two issues.

Absolute tolerance value used in the algorithm to assess closeness to zero in the projected residual (A.T @ (A x - b) entries. Increasing this value relaxes the solution constraints. This value defaults to 10 * max(m, n) * np.spacing(1.).

The default is a good choice if the maximum value within your matrix is on the order of magnitude of 1. If your matrix has a maximum value orders of magnitude larger or smaller than this, it may be better to use a value of max(m, n) * np.linalg.norm(A, order=1) * np.spacing(1.).. However, this has the disadvantage of requiring a norm operation for the A matrix, which is expensive for large problems.

Any thoughts?

Additional context (e.g. screenshots, GIFs)

No response

[ilayn]

I introduced atol based on a wrong implementation and rolled back to the correct implementation rendering atol a no-op keyword. But it was too late as we had a release in between.

We can just mention that it is reserved for future or deprecate it.

[nickodell]

Ah, my bad, I was looking at the 1.14.1 source code. I would be fine with either of those.