[MATH-1039] Added logDensity and logProbability methods to RealDistribution and IntegerDistribution interfaces.

src/changes/changes.xml

@@ -54,6 +54,11 @@ If the output is not quite correct, check for invisible trailing spaces!
     </release>
 
     <release version="4.0" date="XXXX-XX-XX" description="">
+      <action dev="tn" type="add" issue="MATH-1039" due-to="Aleksei Dievskii">
+        Added logDensity(double) to RealDistribution and logProbability(int)
+        to IntegerDistribution interface. The implementations have already been
+        updated in release 3.3. 
+      </action>
       <action dev="tn" type="update" issue="MATH-1155">
         WELL type pseudo-random number generators have been refactored:
         the cached indirection index tables per instance are now stored

src/main/java/org/apache/commons/math4/distribution/AbstractIntegerDistribution.java

@@ -212,19 +212,9 @@ public abstract class AbstractIntegerDistribution implements IntegerDistribution
     }
 
     /**
-     * For a random variable {@code X} whose values are distributed according to
+     * {@inheritDoc}
-     * this distribution, this method returns {@code log(P(X = x))}, where
-     * {@code log} is the natural logarithm. In other words, this method
-     * represents the logarithm of the probability mass function (PMF) for the
-     * distribution. Note that due to the floating point precision and
-     * under/overflow issues, this method will for some distributions be more
-     * precise and faster than computing the logarithm of
-     * {@link #probability(int)}.
      * <p>
-     * The default implementation simply computes the logarithm of {@code probability(x)}.</p>
+     * The default implementation simply computes the logarithm of {@code probability(x)}.
-     *
-     * @param x the point at which the PMF is evaluated
-     * @return the logarithm of the value of the probability mass function at {@code x}
      */
     public double logProbability(int x) {
         return FastMath.log(probability(x));

src/main/java/org/apache/commons/math4/distribution/AbstractRealDistribution.java

@@ -268,18 +268,9 @@ implements RealDistribution, Serializable {
     }
 
     /**
-     * Returns the natural logarithm of the probability density function (PDF) of this distribution
+     * {@inheritDoc}
-     * evaluated at the specified point {@code x}. In general, the PDF is the derivative of the
+     * <p>
-     * {@link #cumulativeProbability(double) CDF}. If the derivative does not exist at {@code x},
+     * The default implementation simply computes the logarithm of {@code density(x)}.
-     * then an appropriate replacement should be returned, e.g. {@code Double.POSITIVE_INFINITY},
-     * {@code Double.NaN}, or the limit inferior or limit superior of the difference quotient. Note
-     * that due to the floating point precision and under/overflow issues, this method will for some
-     * distributions be more precise and faster than computing the logarithm of
-     * {@link #density(double)}. The default implementation simply computes the logarithm of
-     * {@code density(x)}.
-     *
-     * @param x the point at which the PDF is evaluated
-     * @return the logarithm of the value of the probability density function at point {@code x}
      */
     public double logDensity(double x) {
         return FastMath.log(density(x));

src/main/java/org/apache/commons/math4/distribution/IntegerDistribution.java

@@ -21,9 +21,25 @@ import org.apache.commons.math4.exception.OutOfRangeException;
 
 /**
  * Interface for distributions on the integers.
- *
  */
 public interface IntegerDistribution {
+    
+    /**
+     * For a random variable {@code X} whose values are distributed according to
+     * this distribution, this method returns {@code log(P(X = x))}, where
+     * {@code log} is the natural logarithm. In other words, this method
+     * represents the logarithm of the probability mass function (PMF) for the
+     * distribution. Note that due to the floating point precision and
+     * under/overflow issues, this method will for some distributions be more
+     * precise and faster than computing the logarithm of
+     * {@link #probability(int)}.
+     *
+     * @param x the point at which the PMF is evaluated
+     * @return the logarithm of the value of the probability mass function at {@code x}
+     * @since 4.0
+     */
+    double logProbability(int x);
+    
     /**
      * For a random variable {@code X} whose values are distributed according
      * to this distribution, this method returns {@code P(X = x)}. In other

src/main/java/org/apache/commons/math4/distribution/RealDistribution.java

@@ -50,6 +50,23 @@ public interface RealDistribution {
      */
     double density(double x);
 
+    /**
+     * Returns the natural logarithm of the probability density function
+     * (PDF) of this distribution evaluated at the specified point {@code x}.
+     * In general, the PDF is the derivative of the {@link #cumulativeProbability(double) CDF}.
+     * If the derivative does not exist at {@code x}, then an appropriate replacement
+     * should be returned, e.g. {@code Double.POSITIVE_INFINITY}, {@code Double.NaN},
+     * or the limit inferior or limit superior of the difference quotient. Note that
+     * due to the floating point precision and under/overflow issues, this method will
+     * for some distributions be more precise and faster than computing the logarithm of
+     * {@link #density(double)}.
+     *
+     * @param x the point at which the PDF is evaluated
+     * @return the logarithm of the value of the probability density function at point {@code x}
+     * @since 4.0
+     */
+    double logDensity(double x);
+
     /**
      * For a random variable {@code X} whose values are distributed according
      * to this distribution, this method returns {@code P(X <= x)}. In other