SpatialPooler: Needs Additional Documentation re: PotentialRadius

[cogmission]

The SpatialPooler's potentialRadius "silently" gets adjusted in the background during initialization of the OPF or Network API, to be the same size as the inputWidth (as opposed to its default of "16") - which for unsuspecting users of the SpatialPooler outside of those two contexts, can lead to (read: will lead to...) very poor accuracy and performance when using global inhibition!

(@cogmission scrambles on the floor to find missing hair after frantically pulling it out. 👅 )

[rhyolight]

This is not a problem in the SP codebase, but in the NAPI codebase, right?

[cogmission]

In a way. The problem only arises for "raw" SP use (i.e. use of the SP outside of the OPF or Network API), so in a way its exactly the opposite of what you asked? So, in my opinion, the SP itself should be documented with a warning: that way it gets headed off at the source. 😉

[rhyolight]

Wait, that's not what the issue description says. It says either the OPF or NAPI changes the potentialRadius within the SP. But whenever I initialize an SP object directly, the potentialRadius I provide is certainly respected.

From what I can tell from the problem description, the potentialRadius value within an SP is changed from the outside when used in an OPF model or NAPI setup.

[cogmission]

Wait, that's not what the issue description says. It says either the OPF or NAPI changes the potentialRadius within the SP. But whenever I initialize an SP object directly, the potentialRadius I provide is certainly respected.

Yes that is true. Outside of the OPF or NAPI, the potentialRadius is respected. The problem is that the user has to be warned that when using global inhibition, its default of "16" will break performance and it must be set (in the case of "raw" use) to the inputWidth. Does that make sense?

And this PR is about the fact that, without a warning or instruction - the user will never know that this is necessary?

[rhyolight]

This is an educational issue. You want it to be more clear that when globalInhibition=true, the user must specify a potentialRadius that matches the input width of the encoding. Right?

@mrcslws Does that sound right to you as well?

[cogmission]

@scottpurdy
Also, what exactly happens with this parameter when localInhibition=true ? Does it get "tweaked" somewhere, or does the original value stand? What should this be set to, for localInhibition to perform optimally?

[rhyolight]

So there is no localInhibition setting, but if globalInhibition=false we should trust the user to know what they are doing, IMO.

[cogmission]

@rhyolight But I don't understand. Where would the user gain this knowledge of what to do? If there's no documentation for its affect on performance in different scenarios?

[rhyolight]

I think this is another discussion, and any documentation about it should be included in future educational work about topology. Currently, topology is an advanced use-case. We don't have many code examples or instructions of its use because all our current examples do not use it.

I will be coming back to topology soon in the HTM School vids, so I will readdress later.

[cogmission]

@rhyolight Ok, I'm following your lead for how to treat this in HTM.Java also...

Also, it goes without saying that we are all on the edge of our seats, anxiously awaiting more HTM School vids! 😉 Go NMDASpike Lee! :-P

[cogmission]

@rhyolight I think education about this is important. One look at this description for the mapPotential() method and you can see its obvious that this is not a "trivial" topic...

    * If the potentialRadius is greater than or equal to the largest input
      dimension then each column connects to all of the inputs.
    * If the topology is one dimensional, the input space is divided up evenly
      among the columns and each column is centered over its share of the
      inputs.  If the potentialRadius is 5, then each column connects to the
      input it is centered above as well as the 5 inputs to the left of that
      input and the five inputs to the right of that input, wrapping around if
      wrapAround=True.
    * If the topology is two dimensional, the input space is again divided up
      evenly among the columns and each column is centered above its share of
      the inputs.  If the potentialRadius is 5, the column connects to a square
      that has 11 inputs on a side and is centered on the input that the column
      is centered above.

...and I just discovered an example where this is set correctly in hello_sp.py - so it is a "known" fact that this needs to be set, we just didn't have documentation for it?