Skip to content

Rewrite doc of the BCRSMatrix 'implicit' build mode

Oliver Sander requested to merge explain-implicit-buildmode into master

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.

Edited by Oliver Sander

Merge request reports