norvig · May 22, 2018 · Mar 4, 2018 · Mar 4, 2018
diff --git a/core/src/main/java/aima/core/Probability/CategoricalDistribution.java b/core/src/main/java/aima/core/Probability/CategoricalDistribution.java
@@ -0,0 +1,190 @@
+package aima.core.Probability;
+
+import aima.core.Probability.Proposition.AssignmentProposition;
+
+import java.util.Map;
+
+/**
+ * Artificial Intelligence A Modern Approach (4th Edition): page ??.<br>
+ * <br>
+ * A probability distribution for discrete random variables with a finite set of
+ * values. <br>
+ * <b>Note:</b> This definition corresponds to that given in AIMA4e pg. ??, for
+ * a Probability Distribution.
+ *
+ * @author Ciaran O'Reilly
+ * @author samagra
+ * @see <a href="http://en.wikipedia.org/wiki/Probability_distribution"
+ * >Probability Distribution</a>
+ */
+
+public interface CategoricalDistribution extends ProbabilityDistribution {
+
+    public interface Iterator {
+        /**
+         * Called for each possible assignment for the Random Variables
+         * comprising this CategoricalDistribution.
+         *
+         * @param possibleAssignment a possible assignment, &omega;, of variable/value pairs.
+         * @param probability        the probability associated with &omega;
+         */
+        void iterate(Map<RandomVariable, Object> possibleAssignment,
+                     double probability);
+    }
+
+    /**
+     * @return the double[] used to represent the CategoricalDistribution.
+     * @see CategoricalDistribution#setValue(int, double)
+     */
+    double[] getValues();
+
+    /**
+     * Set the value at a specified index within the distribution.
+     *
+     * @param idx
+     * @param value
+     */
+    void setValue(int idx, double value);
+
+    /**
+     * @return the summation of all of the elements within the Distribution.
+     */
+    double getSum();
+
+    /**
+     * Normalize the values comprising this distribution.
+     *
+     * @return this instance with its values normalized.
+     */
+    CategoricalDistribution normalize();
+
+    /**
+     * Retrieve the index into the CategoricalDistribution for the provided set
+     * of values for the random variables comprising the Distribution.
+     *
+     * @param values an ordered set of values for the random variables comprising
+     *               the Distribution (<b>Note:</b> the order must match the order
+     *               of the random variables describing the distribution)
+     * @return the index within the Distribution for the values specified.
+     * @see CategoricalDistribution#getValues()
+     * @see ProbabilityDistribution#getFor()
+     */
+    int getIndex(Object... values);
+
+    /**
+     * Get the marginal probability for the provided variables from this
+     * Distribution creating a new Distribution of the remaining variables with
+     * their values updated with the summed out random variables.<br>
+     * <br>
+     * <br>
+     *
+     * @param vars the random variables to marginalize/sum out.
+     * @return a new Distribution containing any remaining random variables not
+     * summed out and a new set of values updated with the summed out
+     * values.
+     */
+    CategoricalDistribution marginal(RandomVariable... vars);
+
+    /**
+     * Divide the dividend (this) CategoricalDistribution by the divisor to
+     * create a new CategoricalDistribution representing the quotient. The
+     * variables comprising the divisor distribution must be a subset of the
+     * dividend. However, ordering of variables does not matter as the quotient
+     * contains the same variables as the dividend and the internal
+     * implementation logic should handle iterating through the two
+     * distributions correctly, irrespective of the order of their variables.
+     *
+     * @param divisor
+     * @return a new Distribution representing the quotient of the dividend
+     * (this) divided by the divisor.
+     * @throws IllegalArgumentException if the variables of the divisor distribution are not a subset
+     *                                  of the dividend.
+     */
+    CategoricalDistribution divideBy(CategoricalDistribution divisor);
+
+    /**
+     * Multiplication of this Distribution by a given multiplier, creating a new
+     * Distribution representing the product of the two. <b>Note:</b> Is
+     * equivalent to pointwise product calculation on factors.<br>
+     * <br>
+     * <br>
+     * Note: Default Distribution multiplication is not commutative. The reason
+     * is because the order of the variables comprising a Distribution dictate
+     * the ordering of the values for that distribution. For example (the
+     * General case of Baye's rule), using this API method:<br>
+     * <br>
+     * <b>P</b>(Y | X) = (<b>P</b>(X | Y)<b>P</b>(Y))/<b>P</b>(X)<br>
+     * <br>
+     * is NOT true, due to multiplication of distributions not being
+     * commutative. However:<br>
+     * <br>
+     * <b>P</b>(Y | X) = (<b>P</b>(Y)<b>P</b>(X | Y))/<b>P</b>(X)<br>
+     * <br>
+     * is true, using this API.<br>
+     * <br>
+     * The default order of the variable of the Distribution returned is the
+     * order of the variables as they are seen, as read from the left to right
+     * term, for e.g.: <br>
+     * <br>
+     * <b>P</b>(Y)<b>P</b>(X | Y)<br>
+     * <br>
+     * would give a Distribution of the following form: <br>
+     * Y, X<br>
+     * <br>
+     * i.e. an ordered union of the variables from the two distributions. <br>
+     * To override the default order of the product use multiplyByPOS().
+     *
+     * @param multiplier
+     * @return a new Distribution representing the product of this and the
+     * passed in multiplier. The order of the variables comprising the
+     * product distribution is the ordered union of the left term (this)
+     * and the right term (multiplier).
+     * @see CategoricalDistribution#multiplyByPOS(CategoricalDistribution,
+     * RandomVariable...)
+     */
+    CategoricalDistribution multiplyBy(CategoricalDistribution multiplier);
+
+    /**
+     * Multiplication - Product Order Specified (POS). <b>Note:</b> Is
+     * equivalent to pointwise product calculation.<br>
+     * <br>
+     * <br>
+     * Multiplication of this Distribution by a given multiplier, creating a new
+     * Distribution representing the product of the two. The order of the
+     * variables comprising the product will match those specified. For example
+     * (the General case of Baye's rule), using this API method:<br>
+     * <br>
+     * <b>P</b>(Y | X) = (<b>P</b>(X | Y)<b>P</b>(Y), [Y, X])/<b>P</b>(X)<br>
+     * <br>
+     * is true when the correct product order is specified.
+     *
+     * @param multiplier
+     * @param prodVarOrder the order the variables comprising the product are to be in.
+     * @return a new Distribution representing the product of this and the
+     * passed in multiplier. The order of the variables comprising the
+     * product distribution is the order specified.
+     * @see CategoricalDistribution#multiplyBy(CategoricalDistribution)
+     */
+    CategoricalDistribution multiplyByPOS(CategoricalDistribution multiplier,
+                                          RandomVariable... prodVarOrder);
+
+    /**
+     * Iterate over all the possible value assignments for the Random Variables
+     * comprising this CategoricalDistribution.
+     *
+     * @param cdi the CategoricalDistribution Iterator to iterate.
+     */
+    void iterateOver(Iterator cdi);
+
+    /**
+     * Iterate over all possible values assignments for the Random Variables
+     * comprising this CategoricalDistribution that are not in the fixed set of
+     * values. This allows you to iterate over a subset of possible
+     * combinations.
+     *
+     * @param cdi         the CategoricalDistribution Iterator to iterate
+     * @param fixedValues Fixed values for a subset of the Random Variables comprising
+     *                    this CategoricalDistribution.
+     */
+    void iterateOver(Iterator cdi, AssignmentProposition... fixedValues);
+}
diff --git a/core/src/main/java/aima/core/Probability/FiniteProbabilityModel.java b/core/src/main/java/aima/core/Probability/FiniteProbabilityModel.java
@@ -0,0 +1,51 @@
+package aima.core.Probability;
+
+import aima.core.Probability.Proposition.Proposition;
+
+/**
+ * Artificial Intelligence A Modern Approach (4th Edition): page ??.<br>
+ * <br>
+ * A probability model on a discrete, countable set of worlds.
+ *
+ * @author samagra
+ */
+
+public interface FiniteProbabilityModel extends ProbabilityModel {
+
+    /**
+     * <b>P</b>(X,...)<br>
+     *
+     * @param phi the propositions of interest.
+     * @return all the possible values of the propositions &phi;. This is a
+     * Vector of numbers, where we assume a predefined ordering of the
+     * domain of the relevant random variables.
+     */
+    CategoricalDistribution priorDistribution(Proposition... phi);
+
+    /**
+     * Get a conditional distribution. Example:<br>
+     * <br>
+     * <b>P</b>(X | Y) gives the values of P(X = x<sub>i</sub> | Y =
+     * y<sub>j</sub>) for each possible i, j pair.
+     *
+     * @param phi      the proposition for which a probability distribution is to be
+     *                 returned.
+     * @param evidence information we already have.
+     * @return the conditional distribution for <b>P</b>(&phi; | evidence).
+     */
+    CategoricalDistribution posteriorDistribution(Proposition phi,
+                                                  Proposition... evidence);
+
+    /**
+     * Get a distribution on multiple variables. Example, the product rule:<br>
+     * <br>
+     * <b>P</b>(X, Y) gives the values of P(X = x<sub>i</sub> | Y =
+     * y<sub>j</sub>)P(Y = y<sub>j</sub>) for each possible i, j pair.
+     *
+     * @param propositions the propositions for which a joint probability distribution is
+     *                     to be returned.
+     * @return the joint distribution for <b>P</b>(X, Y, ...).
+     */
+    CategoricalDistribution jointDistribution(Proposition... propositions);
+
+}