Skip to content
Snippets Groups Projects
  • Oliver Sander's avatar
    a1feed88
    Rewrite doc of the BCRSMatrix 'implicit' build mode · a1feed88
    Oliver Sander authored
    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:
    a) 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.
    b) 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.
    c) 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.
    a1feed88
    History
    Rewrite doc of the BCRSMatrix 'implicit' build mode
    Oliver Sander authored
    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:
    a) 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.
    b) 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.
    c) 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.
To find the state of this project's repository at the time of any of these versions, check out the tags.