Cognitive Foundry 3.3.2.

ChangeLog.txt

@@ -2,12 +2,43 @@ This file contains the change log for the Cognitive Foundry.
 
 Changes since last release:
 
+Release 3.3.2 (2011-11-07):
+  * Common Core:
+    * Added checkedAdd and checkedMultiply functions to MathUtil, providing a 
+      means for conducting Integer addition and multiplication with explicit
+      checking for overflow and underflow, and throwing an ArithmeticException
+      if they occur.  Java fails silently in integer over(under)flow situations.
+    * Added explicit integer overflow checks to DenseMatrix.  The underlying MTJ
+      library stores dense matrices as a single dimensional arrays of integers, 
+      which in Java are 32-bit.  When creating a matrix with numRows rows and 
+      numColumns columns, if numRows * numColumns is more than 2^31 - 1, a 
+      silent integer overflow would occur, resulting in later 
+      ArrayIndexOutOfBoundsExceptions when attempting to access matrix elements 
+      that didn't get allocated.
+    * Added new methods to DiagonalMatrix interface for multiplying diagonal
+      matrices together and for inverting a DiagonalMatrix.
+    * Optimized operations on diagonal matrices in DiagonalMatrixMTJ.
+    * Added checks to norm method in AbstractVectorSpace and DefaultInfiniteVector
+      for power set to NaN, throwing an ArithmeticException if encountered.
+  * Learning Core:
+    * Optimized matrix multiplies in LogisticRegression to avoid creating dense
+      matrices unnecessarily and to reduce computation time using improved
+      DiagonalMatrix interfaces.
+    * Added regularization and explicit bias estimation to 
+      MultivariateLinearRegression.
+    * Added ConvexReceiverOperatingCharacteristic, which computes the convex
+      hull of the ROC.
+    * Fixed rare corner-case bug in ReceiverOperatingCharacteristic and added
+      optional trapezoidal AUC computation.
+    * Cleaned up constant in MultivariateCumulativeDistributionFunction and
+      added publication references.
+
 Release 3.3.1 (2011-10-06):
   * Common Core:
     * Added NumericMap interface, which provides a mapping of keys to numeric
       values.
     * Added ScalarMap interface, which extends NumericMap to provide a mapping
-      of objects to scalar values represented as doubled.
+      of objects to scalar values represented as doubles.
     * Added AbstractScalarMap and AbstractMutableDoubleMap to provide abstract,
       partial implementations of the ScalarMap interface.
     * Added VectorSpace interface, where a VectorSpace is a type of Ring that

Components/CommonCore/Source/gov/sandia/cognition/math/MathUtil.java

@@ -1,6 +1,6 @@
 /*
  * File:                MathUtil.java
- * Authors:             Justin Basilico
+ * Authors:             Justin Basilico, Kevin Dixon, Zachary Benz
  * Company:             Sandia National Laboratories
  * Project:             Cognitive Foundry
  *
@@ -23,7 +23,7 @@
 /**
  * The {@code MathUtil} class implements mathematical utility functions.
  *
- * @author Justin Basilico
+ * @author Justin Basilico, Kevin Dixon, Zachary Benz
  * @since  2.0
  */
 @CodeReview(
@@ -91,7 +91,7 @@ public static double log2(
         }
     )
     public static double logGammaFunction(
-        double input )
+        final double input )
     {
 
         if (input <= 0.0)
@@ -154,8 +154,8 @@ public static double logGammaFunction(
         }
     )
     public static double lowerIncompleteGammaFunction(
-        double a,
-        double x )
+        final double a,
+        final double x )
     {
 
         if (a <= 0.0)
@@ -211,8 +211,8 @@ else if (x < (a + 1.0))
         notes="Function gser()"
     )
     protected static double incompleteGammaSeriesExpansion(
-        double a,
-        double x )
+        final double a,
+        final double x )
     {
         final int MAX_ITERATIONS = 1000;
         final double EPS = 3e-7;
@@ -281,8 +281,8 @@ protected static double incompleteGammaSeriesExpansion(
         url="http://www.nrbook.com/a/bookcpdf.php"
     )
     public static double incompleteGammaContinuedFraction(
-        double a,
-        double x )
+        final double a,
+        final double x )
     {
 
         LentzMethod lentz = new LentzMethod();
@@ -320,8 +320,8 @@ public static double incompleteGammaContinuedFraction(
         url="http://en.wikipedia.org/wiki/Binomial_coefficient"
     )
     public static int binomialCoefficient(
-        int N,
-        int k )
+        final int N,
+        final int k )
     {
         return (int) Math.round( Math.exp( logBinomialCoefficient(N, k) ) );
     }
@@ -334,8 +334,8 @@ public static int binomialCoefficient(
      * @return Natural logarithm of the binomial coefficient for N choose k
      */
     public static double logBinomialCoefficient(
-        int N,
-        int k )
+        final int N,
+        final int k )
     {
         return logFactorial( N ) - logFactorial( k ) - logFactorial( N - k );
     }
@@ -349,7 +349,7 @@ public static double logBinomialCoefficient(
      * n factorial
      */
     public static double logFactorial(
-        int n )
+        final int n )
     {
         if (n < 0)
         {
@@ -383,8 +383,8 @@ else if (n <= 1)
         url="http://en.wikipedia.org/wiki/Beta_function"
     )
     public static double logBetaFunction(
-        double a,
-        double b )
+        final double a,
+        final double b )
     {
         double ga = logGammaFunction( a );
         double gb = logGammaFunction( b );
@@ -430,9 +430,9 @@ public static double logBetaFunction(
         }
     )
     public static double regularizedIncompleteBetaFunction(
-        double a,
-        double b,
-        double x )
+        final double a,
+        final double b,
+        final double x )
     {
 
         double bt;
@@ -493,9 +493,9 @@ public static double regularizedIncompleteBetaFunction(
 
     )
     protected static double incompleteBetaContinuedFraction(
-        double a,
-        double b,
-        double x )
+        final double a,
+        final double b,
+        final double x )
     {
 
         double apb = a+b;
@@ -559,7 +559,7 @@ protected static double incompleteBetaContinuedFraction(
         notes="Multinomial Beta Function found in the \"Probability density function\" section."
     )
     static public double logMultinomialBetaFunction(
-        Vector input)
+        final Vector input)
     {
         double logsum = 0.0;
         double inputSum = 0.0;
@@ -572,5 +572,121 @@ static public double logMultinomialBetaFunction(
         logsum -= logGammaFunction(inputSum);
         return logsum;
     }
-
+
+    /**
+     * Safely checks for underflow/overflow before adding two integers.  If an
+     * underflow or overflow would occur as a result of the addition, an
+     * {@code ArithmeticException} is thrown.
+     * 
+     * @param a
+     *      The first integer to add
+     * @param b
+     *      The second integer to add
+     * @return
+     *      The sum of integers a and b
+     * @throws ArithmeticException 
+     *      If an underflow or overflow will occur upon adding a and b
+     */
+    @PublicationReference(
+        author={
+            "Tov Are",
+            "Paul van Keep",
+            "Mike Cowlishaw",
+            "Pierre Baillargeon",
+            "Bill Wilkinson",
+            "Patricia Shanahan",
+            "Joseph Bowbeer",
+            "Charles Thomas",
+            "Joel Crisp",
+            "Eric Nagler",
+            "Daniel Leuck",
+            "William Brogden",
+            "Yves Bossu",
+            "Chad Loder"
+        },
+        title="Java Gotchas",
+        type=PublicationType.WebPage,
+        year=2011,
+        url="http://202.38.93.17/bookcd/285/1.iso/faq/gloss/gotchas.html#OVERFLOW",
+        notes="")
+    static public int checkedAdd(
+        final int a,
+        final int b)
+        throws ArithmeticException
+    {
+        if ((a > 0) && (b > Integer.MAX_VALUE - a))
+        {
+            throw new ArithmeticException("Integer Overflow: " +
+                a + " + " + b + " > Integer.MAX_VALUE");
+        }
+        else if ((a < 0) && (b < Integer.MIN_VALUE - a))
+        {
+            throw new ArithmeticException("Integer Underflow: " +
+                a + " + " + b + " < Integer.MIN_VALUE");            
+        }
+        else
+        {
+            return a + b;
+        }
+    }
+
+    /**
+     * Safely checks for overflow before multiplying two integers.  
+     * If an overflow would occur as a result of the
+     * multiplication, an {@code ArithmeticException} is thrown.
+     * 
+     * @param a
+     *      The first integer to multiply
+     * @param b
+     *      The second integer to multiply
+     * @return
+     *      The result of multiplying the integers a and b
+     * @throws ArithmeticException 
+     *      If an overflow will occur upon multiplying a and b
+     */
+    @PublicationReference(
+        author={
+            "Tov Are",
+            "Paul van Keep",
+            "Mike Cowlishaw",
+            "Pierre Baillargeon",
+            "Bill Wilkinson",
+            "Patricia Shanahan",
+            "Joseph Bowbeer",
+            "Charles Thomas",
+            "Joel Crisp",
+            "Eric Nagler",
+            "Daniel Leuck",
+            "William Brogden",
+            "Yves Bossu",
+            "Chad Loder"
+        },
+        title="Java Gotchas",
+        type=PublicationType.WebPage,
+        year=2011,
+        url="http://202.38.93.17/bookcd/285/1.iso/faq/gloss/gotchas.html#OVERFLOW",
+        notes="")
+    static public int checkedMultiply(
+        final int a,
+        final int b)
+        throws ArithmeticException
+    {
+        final long result = (long)a * (long)b;
+        final int desiredHighBits = - ((int)( result >>> 31 ) & 1);
+        final int actualHighBits = (int)( result >>> 32 );
+        if (desiredHighBits == actualHighBits)
+        {
+            return(int)result;
+        }
+        else if (result > 0)
+        {
+            throw new ArithmeticException("Integer Overflow: " +
+                a + " * " + b + " > Integer.MAX_VALUE");
+        }
+        else
+        {
+            throw new ArithmeticException("Integer Underflow: " +
+                a + " * " + b + " < Integer.MIN_VALUE");
+        }
+    }
 }

Components/CommonCore/Source/gov/sandia/cognition/math/matrix/AbstractVectorSpace.java

@@ -122,6 +122,16 @@ public double norm(
         final double power)
     {
         ArgumentChecker.assertIsPositive("power", power);
+        if( Double.isNaN(power) )
+        {
+            throw new ArithmeticException( "Power cannot be NaN" );
+        }
+
+        if( Double.isInfinite(power) )
+        {
+            return this.normInfinity();
+        }
+
         double sum = 0.0;
         for( Entry entry : this )
         {

Components/CommonCore/Source/gov/sandia/cognition/math/matrix/DefaultInfiniteVector.java

@@ -164,6 +164,16 @@ public double norm(
         final double power)
     {
         ArgumentChecker.assertIsPositive("power", power);
+        if( Double.isNaN(power) )
+        {
+            throw new ArithmeticException( "Power cannot be NaN" );
+        }
+
+        if( Double.isInfinite(power) )
+        {
+            return this.normInfinity();
+        }
+
         double sum = 0.0;
         for( VectorSpace.Entry entry : this )
         {

Components/CommonCore/Source/gov/sandia/cognition/math/matrix/DiagonalMatrix.java

@@ -64,10 +64,31 @@ public void setElement(
     // since the off-diagonal elements are necessarily zero
     public DiagonalMatrix dotTimes(
         Matrix matrix );
-
+
+    /**
+     * Multiplies this by the given DiagonalMatrix, leaving this unmodified
+     * @param matrix
+     * DigonalMatrix to multiply this
+     * @return
+     * DiagonalMatrix representing the multiplication
+     */
+    DiagonalMatrix times(
+        DiagonalMatrix matrix );
+
+    /**
+     * Multiplies this by the other diagonal matrix, stores the result in this
+     * @param matrix
+     * Diagonal matrix to multiply this by
+     */
+    void timesEquals(
+        DiagonalMatrix matrix );
+
     public DiagonalMatrix pseudoInverse();
 
     public DiagonalMatrix pseudoInverse(
         double effectiveZero );
-
+
+
+    public DiagonalMatrix inverse();
+
 }

Components/CommonCore/Source/gov/sandia/cognition/math/matrix/VectorSpace.java

@@ -80,7 +80,8 @@ public interface VectorSpace<VectorType extends VectorSpace<VectorType,?>,EntryT
     /**
      * Returns the p-norm of the Vector with the given power.
      * @param power
-     * Power to exponentiate each entry, must be greater than 0.0
+     * Power to exponentiate each entry, must be greater than 0.0,
+     * Double.POSITIVE_INFINITY
      * @return
      * p-norm with the given power.
      */