The confusing part is that the equation shows both parameters being used at the same time. Look at it like this instead:
- Usecase 1: absolute tolerance (
atol):absolute(a - b) <= atol - Usecase 2: relative tolerance (
rtol):absolute(a - b) <= rtol * absolute(b)
An alternative way to implement both with a single tolerance parameter would be to add a flag that determines if the tolerance is relative or absolute. Separating the use-cases like that breaks down in the usecase where array values can be both large and zero. If only one array can have zeros, make that one a and use the asymmetrical equation to your benefit without atol. If either one can have zeros, simply set rtol to some acceptable value for large elements, and set atol to the value you want to kick in for zeros.
You generally want to use rtol: since the precision of numbers and calculations is very much finite, larger numbers will almost always be less precise than smaller ones, and the difference scales linearly (again, in general). You use atol for numbers that are so close to zero that rounding errors are liable to be larger than the number itself, or when the reference number can be zero.
Another way to look at it is atol compares fixed decimal places, while rtol compares significant figures.
A caveat is that both of the default values of the function are non-zero: rtol=1e-05 and atol=1e-08. That means that if you want to use only one or the other of them, you must explicitly set the other to zero.
The confusing part is that the equation shows both parameters being used at the same time. Look at it like this instead:
- Usecase 1: absolute tolerance (
atol):absolute(a - b) <= atol - Usecase 2: relative tolerance (
rtol):absolute(a - b) <= rtol * absolute(b)
An alternative way to implement both with a single tolerance parameter would be to add a flag that determines if the tolerance is relative or absolute. Separating the use-cases like that breaks down in the usecase where array values can be both large and zero. If only one array can have zeros, make that one a and use the asymmetrical equation to your benefit without atol. If either one can have zeros, simply set rtol to some acceptable value for large elements, and set atol to the value you want to kick in for zeros.
You generally want to use rtol: since the precision of numbers and calculations is very much finite, larger numbers will almost always be less precise than smaller ones, and the difference scales linearly (again, in general). You use atol for numbers that are so close to zero that rounding errors are liable to be larger than the number itself, or when the reference number can be zero.
Another way to look at it is atol compares fixed decimal places, while rtol compares significant figures.
A caveat is that both of the default values of the function are non-zero: rtol=1e-05 and atol=1e-08. That means that if you want to use only one or the other of them, you must explicitly set the other to zero.
Which tolerance(s) to use depends on your problem statement. For example, what if my array has a wide domain of values, ranging from 1e-10 to 1e10? A small atol would work well for small values, but poorly for large values, and vice-versa for a large atol. But rtol is perfect in this case because I can specify that the acceptable delta should scale with each value.
I know that the whole XY problem ...
No, there is no XY problem in the question!
The question asks about the function and its parameter. A fact that there is another, "more basic" function with the parameter of the similar meaning doesn't make the problem to be XY. Do not confuse generalization with XY.
For better SEO ... I edited the question
SEO is quite indifferent to the title. It equally finds a question for any matched word in the question body. Moreover, it will be able to find a allclose-only question for isclose search just because these words a "similar" (in some sense).
We edit a title and a question body not for SEO, but for the future readers themselves. For reader it is sufficient to find the same parameter name for look closer to the question. Even if a reader is not aware that functions allclose and isclose are about very similar things, they will find the first paragraph to have a lot of sense for isclose function too.
In total: There is no fundamental problems with the question. It asks about meaning of the specific parameter in the specific function. And does that in the form, which can be easily applied to other function(s) with the same parameter. The answers describe the parameter meaning in a function-agnostic form. The search will find the question even for a string containing another function name.
Your edit was inappropriate, plain and simple. You outright changed the function that OP was asking about. Edits to questions should basically only ever be done to make the question more clear or easier to understand. If you're the asker, that could include adding code, errors, etc. that only you have access to. If you're not the asker, that means you're basically limited to formatting, grammar, spelling, and readability edits only.
You instead changed what the question was asking about altogether. You even had to edit the documentation quote to reflect the new thing you made the question ask about. That's an inappropriate edit any day of the week, even if the constituent part of the function (rtol) is used the same in the new function you asked about as the old function the asker originally asked about.
but reverting to the previous revision without trying to take any single bit from the edit is not cool and behavior like this stops people from contributing to StackOverflow [sic] and cleaning it up.
If your edit had been an improvement, then I'd agree with you. But the onus is on the editor to make sure their edit only improves the question, not changes it completely. A rollback is the appropriate action for such an edit. What's "not cool" is when someone changes a question to ask something completely different, and then gets upset when the question author undoes that change.