Wording in sign function

[Nils Deppe]

Hi Klaus,

Given that Blaze doesn’t do strict equivalence for operator== it would be extremely useful to document which functions do exact comparison. For example, the sign function is documented to give zero if v[i] is zero, but this had me worried that there would be some tolerance there. At least experimentally it appears there isn’t. In general, this seemingly inconsistent behavior between comparisons in different places would be easier to manage as a user if it were explicitly stated on any comparison-based operation whether the comparison is strict or not. Another that comes to mind for being potentially problematic are things like step functions.

Thanks in advance!

Best,

Nils

[Klaus Iglberger]

Hi Nils!

I understand your concern. Do you have a suggestion on how to improve the wording of the documentation of the sign() function?

You may have noticed that for most query functions (equal(), isDefault(), isZero(), IsOne(), isLower(), isUpper(), …) you have the option to pass a RelaxationFlag. With this you can choose between strict or relaxed comparisons. Did you encounter any function that showed unexpected behavior, but did not allow you to choose how comparisons are performed?

Best regards,

Klaus!

[Nils Deppe]

Hi Klaus!

I think just the phrasing “exactly 0” would be enough.

The most unexpected one we’ve encountered is that operator== appears to only compare ~8 digits when using double-precision floating point. I.e.

int main() {
  blaze::DynamicVector<double> a{1.0};
  blaze::DynamicVector<double> b{1.0 + 1.0e-9};
  std::cout << std::boolalpha << (a == b) << "\n";
}

prints true. We found an issue where you explain this, but I think it would be very good to have this stated very clearly in a few different places in the documentation. I haven’t found where in the documentation this behavior is noted, but I think having a “Design Decisions”-type sections or “Important Notes” section in addition to maybe a section on “Comparison Operators” would be good. Since the operator== behavior differs from STL containers, I think it would be nice to have that clearly stated, in addition to what operators actually behave element-wisely the way one would expect from STL containers. We found it quite surprising that a == b behaves differently element-wisely than sin(a), for example. Documenting this very explicitly would help projects avoid and fix bugs in their codes arising from this behavior. My request for the documentation being very explicit arose from the behavior of operator==, since I’m now worried that some other functions in Blaze behave differently if operating on a double or blaze::DynamicVector<double>.

The example you pointed out I also couldn’t find in the documentation. I expected that https://bitbucket.org/blaze-lib/blaze/wiki/Vector Operations#!iszero would describe that such a relaxation flag exists, and how to use it. Should I not be looking at the wiki for documentation?

Somewhat related, it would be nice to be able to control the the value by which things are relaxed. Depending on the application 1e-8 is extremely relaxed. For example, in our use-case 1e-14 would be more appropriate. Looking through the customization documentation: https://bitbucket.org/blaze-lib/blaze/wiki/Customization I don’t see how to change that value, though I didn’t search very thoroughly so it could be that I just missed it. The Thresholds section appears to be about when to switch between different implementations of the operations for better performance.

Thanks!

Best,

Nils

‌