Rewrite doc of the BCRSMatrix 'implicit' build mode

Circumstances forced me to finally learn what the BCRSMatrix 'implicit' build mode really does, and where its limitations come from. I had to read the code for that. As it turns out, the documentation of the mode is quite misleading. My main gripe is that the code uses two different auxiliary data structures, but the documentation calls them both 'overflow'. This problem even extends to the variable naming in the code. Behold: the parameter 'overflowsize' is NOT the size of the member 'overflow'. It doesn't even have anything to do with that member...

To improve the situation, this patch does three things:

1. It rewrites the documentation. In particular, the 'overflow area' is now clearly distinguished from the 'compression buffer'. The latter is a new word I introduce.

2. It renames the BCRSMatrix method parameter _overflowsize to compressionBufferSize, because that is what it is: That parameter has nothing to do with the 'overflow' data member, or even the concept of 'overflowing' in general.

3. It renames the exception 'ImplicitModeOverflowExhausted' to 'ImplicitModeCompressionBufferExhausted', for the same reason. This is the only interface changes. The code keeps the old exception for backward-compatibility, but makes it trigger a deprecation warning.

changed the description

added 53 commits

• 29fd9b9c...de175a9f - 52 commits from branch master
• 868c992e - Rewrite doc of the BCRSMatrix 'implicit' build mode

Compare with previous version

@dominic , didn't you write parts of the implicitbuild mode? Is the new text okay with you?

IMHO this looks good and should be merged. @dominic can you have a look and merge if you are OK with the semantics?...

I really like the improved documentation, especially since it is now clear, which cases lead to an error. But I have two comments:

• compressionBufferSize is equally misleading since it gives the impression that this is only used during compression. In fact it also used if nnz exceeds n*avg. But I don't know any better alternative and since the precise semantics is now documented, I also don't care for the naming that much.
• avg is (still) really misleading, because it gives the impression that you're good if avg is nnz/n. But this is far from being true. While we now have a precise documentation (in terms of a formula), having an explicit warning (maybe with a failing example) that this heavily depends on the ordering would make the situation less abstract.

Notice that this is no criticism but just a suggestion how this could be improved even further.

Thanks for your comments. I think compressionBuffer is okay, because that buffer is used by the compression algorithm, no matter whether nnz exceeds n*avg or not.

I am sure this could be improved further, but my time and energy ends here. :-)

added 1 commit

• a1feed88 - Rewrite doc of the BCRSMatrix 'implicit' build mode

Compare with previous version

resolved all threads

mentioned in commit 95b8fa3c

merged