Merge pull request #499 from cogmission/zero_overlap_tests

Add 4 SP Zero Overlap Tests & Parameter KEY docs

Author: cogmission

src/main/java/org/numenta/nupic/Parameters.java

@@ -107,8 +107,8 @@ public class Parameters implements Persistable {
         defaultSpatialParams.put(KEY.LOCAL_AREA_DENSITY, -1.0);
         defaultSpatialParams.put(KEY.NUM_ACTIVE_COLUMNS_PER_INH_AREA, 10.0);
         defaultSpatialParams.put(KEY.STIMULUS_THRESHOLD, 0.0);
-        defaultSpatialParams.put(KEY.SYN_PERM_INACTIVE_DEC, 0.008);//0.01
-        defaultSpatialParams.put(KEY.SYN_PERM_ACTIVE_INC, 0.05);//0.1
+        defaultSpatialParams.put(KEY.SYN_PERM_INACTIVE_DEC, 0.008);
+        defaultSpatialParams.put(KEY.SYN_PERM_ACTIVE_INC, 0.05);
         defaultSpatialParams.put(KEY.SYN_PERM_CONNECTED, 0.10);
         defaultSpatialParams.put(KEY.SYN_PERM_BELOW_STIMULUS_INC, 0.01);
         defaultSpatialParams.put(KEY.SYN_PERM_TRIM_THRESHOLD, 0.05);
@@ -223,7 +223,7 @@ public static enum KEY {
          * predicted but inactive segments are decremented.
          */
         PREDICTED_SEGMENT_DECREMENT("predictedSegmentDecrement", Double.class, 0.0, 9.0),
-        /** Remove this and add Logging (slf4j) */
+        /** TODO: Remove this and add Logging (slf4j) */
         //TM_VERBOSITY("tmVerbosity", Integer.class, 0, 10),
 
 
@@ -234,21 +234,136 @@ public static enum KEY {
          * using the Network API (which sets this automatically) 
          */
         POTENTIAL_RADIUS("potentialRadius", Integer.class),
+        /**
+         * The percent of the inputs, within a column's potential radius, that a
+         * column can be connected to.  If set to 1, the column will be connected
+         * to every input within its potential radius. This parameter is used to
+         * give each column a unique potential pool when a large potentialRadius
+         * causes overlap between the columns. At initialization time we choose
+         * ((2*potentialRadius + 1)^(# inputDimensions) * potentialPct) input bits
+         * to comprise the column's potential pool.
+         */
         POTENTIAL_PCT("potentialPct", Double.class), //TODO add range here?
+        /**
+         * If true, then during inhibition phase the winning columns are selected
+         * as the most active columns from the region as a whole. Otherwise, the
+         * winning columns are selected with respect to their local neighborhoods.
+         * Using global inhibition boosts performance x60.
+         */
         GLOBAL_INHIBITION("globalInhibition", Boolean.class),
+        /**
+         * The inhibition radius determines the size of a column's local
+         * neighborhood.  A cortical column must overcome the overlap score of
+         * columns in its neighborhood in order to become active. This radius is
+         * updated every learning round. It grows and shrinks with the average
+         * number of connected synapses per column.
+         */
         INHIBITION_RADIUS("inhibitionRadius", Integer.class, 0, null),
+        /**
+         * The desired density of active columns within a local inhibition area
+         * (the size of which is set by the internally calculated inhibitionRadius,
+         * which is in turn determined from the average size of the connected
+         * potential pools of all columns). The inhibition logic will insure that
+         * at most N columns remain ON within a local inhibition area, where
+         * N = localAreaDensity * (total number of columns in inhibition area).
+         */
         LOCAL_AREA_DENSITY("localAreaDensity", Double.class), //TODO add range here?
+        /**
+         * An alternate way to control the density of the active columns. If
+         * numActiveColumnsPerInhArea is specified then localAreaDensity must be
+         * less than 0, and vice versa.  When using numActiveColumnsPerInhArea, the
+         * inhibition logic will insure that at most 'numActiveColumnsPerInhArea'
+         * columns remain ON within a local inhibition area (the size of which is
+         * set by the internally calculated inhibitionRadius, which is in turn
+         * determined from the average size of the connected receptive fields of all
+         * columns). When using this method, as columns learn and grow their
+         * effective receptive fields, the inhibitionRadius will grow, and hence the
+         * net density of the active columns will *decrease*. This is in contrast to
+         * the localAreaDensity method, which keeps the density of active columns
+         * the same regardless of the size of their receptive fields.
+         */
         NUM_ACTIVE_COLUMNS_PER_INH_AREA("numActiveColumnsPerInhArea", Double.class),//TODO add range here?
+        /**
+         * This is a number specifying the minimum number of synapses that must be
+         * on in order for a columns to turn ON. The purpose of this is to prevent
+         * noise input from activating columns. Specified as a percent of a fully
+         * grown synapse.
+         */
         STIMULUS_THRESHOLD("stimulusThreshold", Double.class), //TODO add range here?
+        /**
+         * The amount by which an inactive synapse is decremented in each round.
+         * Specified as a percent of a fully grown synapse.
+         */
         SYN_PERM_INACTIVE_DEC("synPermInactiveDec", Double.class, 0.0, 1.0),
+        /**
+         * The amount by which an active synapse is incremented in each round.
+         * Specified as a percent of a fully grown synapse.
+         */
         SYN_PERM_ACTIVE_INC("synPermActiveInc", Double.class, 0.0, 1.0),
+        /**
+         * The default connected threshold. Any synapse whose permanence value is
+         * above the connected threshold is a "connected synapse", meaning it can
+         * contribute to the cell's firing.
+         */
         SYN_PERM_CONNECTED("synPermConnected", Double.class, 0.0, 1.0),
+        /**
+         * <b>WARNING:</b> This is a <i><b>derived</b><i> value, and is overwritten
+         * by the SpatialPooler algorithm's initialization.
+         * 
+         * The permanence increment amount for columns that have not been
+         * recently active
+         */
         SYN_PERM_BELOW_STIMULUS_INC("synPermBelowStimulusInc", Double.class, 0.0, 1.0),
+        /**
+         * <b>WARNING:</b> This is a <i><b>derived</b><i> value, and is overwritten
+         * by the SpatialPooler algorithm's initialization.
+         * 
+         * Values below this are "clipped" and zero'd out.
+         */
         SYN_PERM_TRIM_THRESHOLD("synPermTrimThreshold", Double.class, 0.0, 1.0),
+        /**
+         * A number between 0 and 1.0, used to set a floor on how often a column
+         * should have at least stimulusThreshold active inputs. Periodically, each
+         * column looks at the overlap duty cycle of all other columns within its
+         * inhibition radius and sets its own internal minimal acceptable duty cycle
+         * to: minPctDutyCycleBeforeInh * max(other columns' duty cycles).  On each
+         * iteration, any column whose overlap duty cycle falls below this computed
+         * value will  get all of its permanence values boosted up by
+         * synPermActiveInc. Raising all permanences in response to a sub-par duty
+         * cycle before  inhibition allows a cell to search for new inputs when
+         * either its previously learned inputs are no longer ever active, or when
+         * the vast majority of them have been "hijacked" by other columns.
+         */
         MIN_PCT_OVERLAP_DUTY_CYCLES("minPctOverlapDutyCycles", Double.class),//TODO add range here?
+        /**
+         * A number between 0 and 1.0, used to set a floor on how often a column
+         * should be activate.  Periodically, each column looks at the activity duty
+         * cycle of all other columns within its inhibition radius and sets its own
+         * internal minimal acceptable duty cycle to: minPctDutyCycleAfterInh *
+         * max(other columns' duty cycles).  On each iteration, any column whose duty
+         * cycle after inhibition falls below this computed value will get its
+         * internal boost factor increased.
+         */
         MIN_PCT_ACTIVE_DUTY_CYCLES("minPctActiveDutyCycles", Double.class),//TODO add range here?
+        /**
+         * The period used to calculate duty cycles. Higher values make it take
+         * longer to respond to changes in boost or synPerConnectedCell. Shorter
+         * values make it more unstable and likely to oscillate.
+         */
         DUTY_CYCLE_PERIOD("dutyCyclePeriod", Integer.class),//TODO add range here?
+        /**
+         * The maximum overlap boost factor. Each column's overlap gets multiplied
+         * by a boost factor before it gets considered for inhibition.  The actual
+         * boost factor for a column is number between 1.0 and maxBoost. A boost
+         * factor of 1.0 is used if the duty cycle is >= minOverlapDutyCycle,
+         * maxBoost is used if the duty cycle is 0, and any duty cycle in between is
+         * linearly extrapolated from these 2 endpoints.
+         */
         MAX_BOOST("maxBoost", Double.class), //TODO add range here?
+        /**
+         * Determines if inputs at the beginning and end of an input dimension should
+         * be considered neighbors when mapping columns to inputs.
+         */
         WRAP_AROUND("wrapAround", Boolean.class),
 
         ///////////// SpatialPooler / Network Parameter(s) /////////////

src/main/java/org/numenta/nupic/algorithms/SpatialPooler.java

@@ -22,7 +22,6 @@
 package org.numenta.nupic.algorithms;
 
 import java.util.Arrays;
-import java.util.Comparator;
 import java.util.stream.IntStream;
 
 import org.numenta.nupic.model.Column;
@@ -808,28 +807,23 @@ public int[] inhibitColumns(Connections c, double[] overlaps) {
     public int[] inhibitColumnsGlobal(Connections c, double[] overlaps, double density) {
         int numCols = c.getNumColumns();
         int numActive = (int)(density * numCols);
-        
-        Comparator<Pair<Integer, Double>> comparator = 
-            (p1, p2) -> { 
-                int p1key = p1.getFirst();
-                int p2key = p2.getFirst();
-                double p1val = p1.getSecond();
-                double p2val = p2.getSecond();
-                if(Math.abs(p2val - p1val) < 0.000000001) {
-                    return Math.abs(p2key - p1key) < 0.000000001 ? 0 : p2key > p1key ? 1 : -1;
-                } else {
-                    return p2val > p1val ? 1 : -1;
-                }
-            };
-        int[] inhibit = IntStream.range(0,overlaps.length)
+ 
+        int[] sortedWinnerIndices = IntStream.range(0,overlaps.length)
             .mapToObj(i-> new Pair<>(i,overlaps[i]))
-            .sorted(comparator)
+            .sorted(c.inhibitionComparator)
             .mapToInt(Pair<Integer,Double>::getFirst)
-            .limit(numActive)
-            .sorted()
             .toArray();
 
-        return inhibit;
+        // Enforce the stimulus threshold
+        double stimulusThreshold = c.getStimulusThreshold();
+        int start = sortedWinnerIndices.length - numActive;
+        while(start < sortedWinnerIndices.length) {
+            int i = sortedWinnerIndices[start];
+            if(overlaps[i] >= stimulusThreshold) break;
+            ++start;
+        }
+        
+        return IntStream.of(sortedWinnerIndices).skip(start).toArray();
     }
 
     /**

src/main/java/org/numenta/nupic/model/Connections.java

@@ -31,6 +31,7 @@
 import org.numenta.nupic.util.Topology;
 import org.numenta.nupic.util.UniversalRandom;
 
+import chaschev.lang.Pair;
 import gnu.trove.list.array.TIntArrayList;
 
 /**
@@ -231,6 +232,19 @@ public class Connections implements Persistable {
         return c1 == c2 ? 0 : c1 > c2 ? 1 : -1;
     };
 
+    /** Sorting Lambda used for SpatialPooler inhibition */
+    public Comparator<Pair<Integer, Double>> inhibitionComparator = (Comparator<Pair<Integer, Double>> & Serializable)
+        (p1, p2) -> { 
+            int p1key = p1.getFirst();
+            int p2key = p2.getFirst();
+            double p1val = p1.getSecond();
+            double p2val = p2.getSecond();
+            if(Math.abs(p2val - p1val) < 0.000000001) {
+                return Math.abs(p2key - p1key) < 0.000000001 ? 0 : p2key > p1key ? -1 : 1;
+            } else {
+                return p2val > p1val ? -1 : 1;
+            }
+        };
 
     ////////////////////////////////////////
     //       Connections Constructor      //

src/test/java/org/numenta/nupic/algorithms/SpatialPoolerTest.java

@@ -226,6 +226,123 @@ public int[] inhibitColumns(Connections c, double[] overlaps) {
         }
     }
 
+    /**
+     * When stimulusThreshold is 0, allow columns without any overlap to become
+     * active. This test focuses on the global inhibition code path.
+     */
+    @Test
+    public void testZeroOverlap_NoStimulusThreshold_GlobalInhibition() {
+        int inputSize = 10;
+        int nColumns = 20;
+        parameters = Parameters.getSpatialDefaultParameters();
+        parameters.set(KEY.INPUT_DIMENSIONS, new int[] { inputSize });
+        parameters.set(KEY.COLUMN_DIMENSIONS, new int[] { nColumns });
+        parameters.set(KEY.POTENTIAL_RADIUS, 10);
+        parameters.set(KEY.GLOBAL_INHIBITION, true);
+        parameters.set(KEY.NUM_ACTIVE_COLUMNS_PER_INH_AREA, 3.0);
+        parameters.set(KEY.STIMULUS_THRESHOLD, 0.0);
+        parameters.set(KEY.RANDOM, new UniversalRandom(42));
+        parameters.set(KEY.SEED, 42);
+        
+        SpatialPooler sp = new SpatialPooler();
+        Connections cn = new Connections();
+        parameters.apply(cn);
+        sp.init(cn);
+        
+        int[] activeArray = new int[nColumns];
+        sp.compute(cn, new int[inputSize], activeArray, true);
+        
+        assertEquals(3, ArrayUtils.where(activeArray, ArrayUtils.INT_GREATER_THAN_0).length);
+    }
+    
+    /**
+     * When stimulusThreshold is > 0, don't allow columns without any overlap to
+     * become active. This test focuses on the global inhibition code path.
+     */
+    @Test
+    public void testZeroOverlap_StimulusThreshold_GlobalInhibition() {
+        int inputSize = 10;
+        int nColumns = 20;
+        parameters = Parameters.getSpatialDefaultParameters();
+        parameters.set(KEY.INPUT_DIMENSIONS, new int[] { inputSize });
+        parameters.set(KEY.COLUMN_DIMENSIONS, new int[] { nColumns });
+        parameters.set(KEY.POTENTIAL_RADIUS, 10);
+        parameters.set(KEY.GLOBAL_INHIBITION, true);
+        parameters.set(KEY.NUM_ACTIVE_COLUMNS_PER_INH_AREA, 3.0);
+        parameters.set(KEY.STIMULUS_THRESHOLD, 1.0);
+        parameters.set(KEY.RANDOM, new UniversalRandom(42));
+        parameters.set(KEY.SEED, 42);
+        
+        SpatialPooler sp = new SpatialPooler();
+        Connections cn = new Connections();
+        parameters.apply(cn);
+        sp.init(cn);
+        
+        int[] activeArray = new int[nColumns];
+        sp.compute(cn, new int[inputSize], activeArray, true);
+        
+        assertEquals(0, ArrayUtils.where(activeArray, ArrayUtils.INT_GREATER_THAN_0).length);
+    }
+    
+    @Test
+    public void testZeroOverlap_NoStimulusThreshold_LocalInhibition() {
+        int inputSize = 10;
+        int nColumns = 20;
+        parameters = Parameters.getSpatialDefaultParameters();
+        parameters.set(KEY.INPUT_DIMENSIONS, new int[] { inputSize });
+        parameters.set(KEY.COLUMN_DIMENSIONS, new int[] { nColumns });
+        parameters.set(KEY.POTENTIAL_RADIUS, 5);
+        parameters.set(KEY.GLOBAL_INHIBITION, false);
+        parameters.set(KEY.NUM_ACTIVE_COLUMNS_PER_INH_AREA, 1.0);
+        parameters.set(KEY.STIMULUS_THRESHOLD, 0.0);
+        parameters.set(KEY.RANDOM, new UniversalRandom(42));
+        parameters.set(KEY.SEED, 42);
+        
+        SpatialPooler sp = new SpatialPooler();
+        Connections cn = new Connections();
+        parameters.apply(cn);
+        sp.init(cn);
+        
+        // This exact number of active columns is determined by the inhibition
+        // radius, which changes based on the random synapses (i.e. weird math).
+        // Force it to a known number.
+        cn.setInhibitionRadius(2);
+        
+        int[] activeArray = new int[nColumns];
+        sp.compute(cn, new int[inputSize], activeArray, true);
+        
+        assertEquals(6, ArrayUtils.where(activeArray, ArrayUtils.INT_GREATER_THAN_0).length);
+    }
+    
+    /**
+     * When stimulusThreshold is > 0, don't allow columns without any overlap to
+     * become active. This test focuses on the local inhibition code path.
+     */
+    @Test
+    public void testZeroOverlap_StimulusThreshold_LocalInhibition() {
+        int inputSize = 10;
+        int nColumns = 20;
+        parameters = Parameters.getSpatialDefaultParameters();
+        parameters.set(KEY.INPUT_DIMENSIONS, new int[] { inputSize });
+        parameters.set(KEY.COLUMN_DIMENSIONS, new int[] { nColumns });
+        parameters.set(KEY.POTENTIAL_RADIUS, 10);
+        parameters.set(KEY.GLOBAL_INHIBITION, false);
+        parameters.set(KEY.NUM_ACTIVE_COLUMNS_PER_INH_AREA, 3.0);
+        parameters.set(KEY.STIMULUS_THRESHOLD, 1.0);
+        parameters.set(KEY.RANDOM, new UniversalRandom(42));
+        parameters.set(KEY.SEED, 42);
+        
+        SpatialPooler sp = new SpatialPooler();
+        Connections cn = new Connections();
+        parameters.apply(cn);
+        sp.init(cn);
+        
+        int[] activeArray = new int[nColumns];
+        sp.compute(cn, new int[inputSize], activeArray, true);
+        
+        assertEquals(0, ArrayUtils.where(activeArray, ArrayUtils.INT_GREATER_THAN_0).length);
+    }
+    
     @Test
     public void testOverlapsOutput() {
         parameters = Parameters.getSpatialDefaultParameters();
@@ -1558,6 +1675,7 @@ public void testInhibitColumnsGlobal() {
         double[] overlaps = new double[] { 1, 2, 1, 4, 8, 3, 12, 5, 4, 1 };
         int[] active = sp.inhibitColumnsGlobal(mem, overlaps, density);
         int[] trueActive = new int[] { 4, 6, 7 };
+        Arrays.sort(active);
         assertTrue(Arrays.equals(trueActive, active));
 
         density = 0.5;

src/test/java/org/numenta/nupic/network/RegionTest.java

@@ -321,6 +321,7 @@ public void testMultiLayerAssemblyNoSensor() {
         p.set(KEY.SYN_PERM_INACTIVE_DEC, 0.1);
         p.set(KEY.SYN_PERM_ACTIVE_INC, 0.1);
         p.set(KEY.SYN_PERM_TRIM_THRESHOLD, 0.05);
+        p.set(KEY.GLOBAL_INHIBITION, true);
         p.set(KEY.SYN_PERM_CONNECTED, 0.4);
         p.set(KEY.MAX_BOOST, 10.0);
         p.set(KEY.DUTY_CYCLE_PERIOD, 7);
@@ -358,7 +359,7 @@ public void testMultiLayerAssemblyNoSensor() {
             }
         });
 
-        final int NUM_CYCLES = 400;
+        final int NUM_CYCLES = 500;
         final int INPUT_GROUP_COUNT = 7; // Days of Week
         Map<String, Object> multiInput = new HashMap<>();
         for(int i = 0;i < NUM_CYCLES;i++) {