Add throw declarations for filter package, javadoc formatting.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1381332 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math3/filter/DefaultMeasurementModel.java

@@ -16,12 +16,14 @@
  */
 package org.apache.commons.math3.filter;
 
+import org.apache.commons.math3.exception.DimensionMismatchException;
+import org.apache.commons.math3.exception.NoDataException;
+import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.linear.Array2DRowRealMatrix;
 import org.apache.commons.math3.linear.RealMatrix;
 
 /**
- * Default implementation of a {@link MeasurementModel} for the use with a
+ * Default implementation of a {@link MeasurementModel} for the use with a {@link KalmanFilter}.
- * {@link KalmanFilter}.
  *
  * @since 3.0
  * @version $Id$
@@ -40,13 +42,22 @@ public class DefaultMeasurementModel implements MeasurementModel {
     private RealMatrix measurementNoise;
 
     /**
-     * Create a new {@link MeasurementModel}, taking double arrays as input
+     * Create a new {@link MeasurementModel}, taking double arrays as input parameters for the
-     * parameters for the respective measurement matrix and noise.
+     * respective measurement matrix and noise.
      *
-     * @param measMatrix the measurement matrix
+     * @param measMatrix
-     * @param measNoise the measurement noise matrix
+     *            the measurement matrix
+     * @param measNoise
+     *            the measurement noise matrix
+     * @throws NullArgumentException
+     *             if any of the input matrices is {@code null}
+     * @throws NoDataException
+     *             if any row / column dimension of the input matrices is zero
+     * @throws DimensionMismatchException
+     *             if any of the input matrices is non-rectangular
      */
-    public DefaultMeasurementModel(final double[][] measMatrix, final double[][] measNoise) {
+    public DefaultMeasurementModel(final double[][] measMatrix, final double[][] measNoise)
+            throws NullArgumentException, NoDataException, DimensionMismatchException {
         this(new Array2DRowRealMatrix(measMatrix), new Array2DRowRealMatrix(measNoise));
     }
 

src/main/java/org/apache/commons/math3/filter/DefaultProcessModel.java

@@ -16,28 +16,28 @@
  */
 package org.apache.commons.math3.filter;
 
+import org.apache.commons.math3.exception.DimensionMismatchException;
+import org.apache.commons.math3.exception.NoDataException;
+import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.linear.Array2DRowRealMatrix;
 import org.apache.commons.math3.linear.ArrayRealVector;
 import org.apache.commons.math3.linear.RealMatrix;
 import org.apache.commons.math3.linear.RealVector;
 
 /**
- * Default implementation of a {@link ProcessModel} for the use with a
+ * Default implementation of a {@link ProcessModel} for the use with a {@link KalmanFilter}.
- * {@link KalmanFilter}.
  *
  * @since 3.0
  * @version $Id$
  */
 public class DefaultProcessModel implements ProcessModel {
     /**
-     * The state transition matrix, used to advance the internal state
+     * The state transition matrix, used to advance the internal state estimation each time-step.
-     * estimation each time-step.
      */
     private RealMatrix stateTransitionMatrix;
 
     /**
-     * The control matrix, used to integrate a control input into the state
+     * The control matrix, used to integrate a control input into the state estimation.
-     * estimation.
      */
     private RealMatrix controlMatrix;
 
@@ -51,20 +51,32 @@ public class DefaultProcessModel implements ProcessModel {
     private RealMatrix initialErrorCovMatrix;
 
     /**
-     * Create a new {@link ProcessModel}, taking double arrays as input
+     * Create a new {@link ProcessModel}, taking double arrays as input parameters.
-     * parameters.
      *
-     * @param stateTransition the state transition matrix
+     * @param stateTransition
-     * @param control the control matrix
+     *            the state transition matrix
-     * @param processNoise the process noise matrix
+     * @param control
-     * @param initialStateEstimate the initial state estimate vector
+     *            the control matrix
-     * @param initialErrorCovariance the initial error covariance matrix
+     * @param processNoise
+     *            the process noise matrix
+     * @param initialStateEstimate
+     *            the initial state estimate vector
+     * @param initialErrorCovariance
+     *            the initial error covariance matrix
+     * @throws NullArgumentException
+     *             if any of the input arrays is {@code null}
+     * @throws NoDataException
+     *             if any row / column dimension of the input matrices is zero
+     * @throws DimensionMismatchException
+     *             if any of the input matrices is non-rectangular
      */
     public DefaultProcessModel(final double[][] stateTransition,
                                final double[][] control,
                                final double[][] processNoise,
                                final double[] initialStateEstimate,
-                               final double[][] initialErrorCovariance) {
+                               final double[][] initialErrorCovariance)
+            throws NullArgumentException, NoDataException, DimensionMismatchException {
+
         this(new Array2DRowRealMatrix(stateTransition),
                 new Array2DRowRealMatrix(control),
                 new Array2DRowRealMatrix(processNoise),
@@ -73,31 +85,47 @@ public class DefaultProcessModel implements ProcessModel {
     }
 
     /**
-     * Create a new {@link ProcessModel}, taking double arrays as input
+     * Create a new {@link ProcessModel}, taking double arrays as input parameters.
-     * parameters. The initial state estimate and error covariance are omitted
+     * <p>
-     * and will be initialized by the {@link KalmanFilter} to default values.
+     * The initial state estimate and error covariance are omitted and will be initialized by the
+     * {@link KalmanFilter} to default values.
      *
-     * @param stateTransition the state transition matrix
+     * @param stateTransition
-     * @param control the control matrix
+     *            the state transition matrix
-     * @param processNoise the process noise matrix
+     * @param control
+     *            the control matrix
+     * @param processNoise
+     *            the process noise matrix
+     * @throws NullArgumentException
+     *             if any of the input arrays is {@code null}
+     * @throws NoDataException
+     *             if any row / column dimension of the input matrices is zero
+     * @throws DimensionMismatchException
+     *             if any of the input matrices is non-rectangular
      */
     public DefaultProcessModel(final double[][] stateTransition,
                                final double[][] control,
-                               final double[][] processNoise) {
+                               final double[][] processNoise)
+            throws NullArgumentException, NoDataException, DimensionMismatchException {
+
         this(new Array2DRowRealMatrix(stateTransition),
                 new Array2DRowRealMatrix(control),
                 new Array2DRowRealMatrix(processNoise), null, null);
     }
 
     /**
-     * Create a new {@link ProcessModel}, taking double arrays as input
+     * Create a new {@link ProcessModel}, taking double arrays as input parameters.
-     * parameters.
      *
-     * @param stateTransition the state transition matrix
+     * @param stateTransition
-     * @param control the control matrix
+     *            the state transition matrix
-     * @param processNoise the process noise matrix
+     * @param control
-     * @param initialStateEstimate the initial state estimate vector
+     *            the control matrix
-     * @param initialErrorCovariance the initial error covariance matrix
+     * @param processNoise
+     *            the process noise matrix
+     * @param initialStateEstimate
+     *            the initial state estimate vector
+     * @param initialErrorCovariance
+     *            the initial error covariance matrix
      */
     public DefaultProcessModel(final RealMatrix stateTransition,
                                final RealMatrix control,

src/main/java/org/apache/commons/math3/filter/KalmanFilter.java

@@ -17,6 +17,7 @@
 package org.apache.commons.math3.filter;
 
 import org.apache.commons.math3.exception.DimensionMismatchException;
+import org.apache.commons.math3.exception.NullArgumentException;
 import org.apache.commons.math3.linear.Array2DRowRealMatrix;
 import org.apache.commons.math3.linear.ArrayRealVector;
 import org.apache.commons.math3.linear.CholeskyDecomposition;
@@ -26,6 +27,7 @@ import org.apache.commons.math3.linear.MatrixUtils;
 import org.apache.commons.math3.linear.NonSquareMatrixException;
 import org.apache.commons.math3.linear.RealMatrix;
 import org.apache.commons.math3.linear.RealVector;
+import org.apache.commons.math3.linear.SingularMatrixException;
 import org.apache.commons.math3.util.MathUtils;
 
 /**
@@ -43,6 +45,7 @@ import org.apache.commons.math3.util.MathUtils;
  * <i>z<sub>k</sub></i> = <b>H</b><i>x<sub>k</sub></i> + <i>v<sub>k</sub></i>.
  * </pre>
  *
+ * <p>
  * The random variables <i>w<sub>k</sub></i> and <i>v<sub>k</sub></i> represent
  * the process and measurement noise and are assumed to be independent of each
  * other and distributed with normal probability (white noise).
@@ -52,8 +55,6 @@ import org.apache.commons.math3.util.MathUtils;
  * <li>predict: project the current state estimate ahead in time</li>
  * <li>correct: adjust the projected estimate by an actual measurement</li>
  * </ol>
- * </p>
- * <br/>
  * <p>
  * The Kalman filter is initialized with a {@link ProcessModel} and a
  * {@link MeasurementModel}, which contain the corresponding transformation and
@@ -68,7 +69,6 @@ import org.apache.commons.math3.util.MathUtils;
  * <li>R - measurement noise covariance matrix</li>
  * <li>P - error covariance matrix</li>
  * </ul>
- * </p>
  *
  * @see <a href="http://www.cs.unc.edu/~welch/kalman/">Kalman filter
  *      resources</a>
@@ -108,16 +108,19 @@ public class KalmanFilter {
      *            the model defining the underlying process dynamics
      * @param measurement
      *            the model defining the given measurement characteristics
-     * @throws org.apache.commons.math3.exception.NullArgumentException
+     * @throws NullArgumentException
-     *             if any of the given inputs is null (except for the control
+     *             if any of the given inputs is null (except for the control matrix)
-     *             matrix)
      * @throws NonSquareMatrixException
      *             if the transition matrix is non square
+     * @throws DimensionMismatchException
+     *             if the column dimension of the transition matrix does not match the dimension of the
+     *             initial state estimation vector
      * @throws MatrixDimensionMismatchException
      *             if the matrix dimensions do not fit together
      */
-    public KalmanFilter(final ProcessModel process,
+    public KalmanFilter(final ProcessModel process, final MeasurementModel measurement)
-                        final MeasurementModel measurement) {
+            throws NullArgumentException, NonSquareMatrixException, DimensionMismatchException,
+                   MatrixDimensionMismatchException {
 
         MathUtils.checkNotNull(process);
         MathUtils.checkNotNull(measurement);
@@ -151,8 +154,7 @@ public class KalmanFilter {
         // set the initial state estimate to a zero vector if it is not
         // available from the process model
         if (processModel.getInitialStateEstimate() == null) {
-            stateEstimation =
+            stateEstimation = new ArrayRealVector(transitionMatrix.getColumnDimension());
-                new ArrayRealVector(transitionMatrix.getColumnDimension());
         } else {
             stateEstimation = processModel.getInitialStateEstimate();
         }
@@ -279,18 +281,19 @@ public class KalmanFilter {
      * @throws DimensionMismatchException
      *             if the dimension of the control vector does not fit
      */
-    public void predict(final double[] u) {
+    public void predict(final double[] u) throws DimensionMismatchException {
         predict(new ArrayRealVector(u));
     }
 
     /**
      * Predict the internal state estimation one time step ahead.
      *
-     * @param u the control vector
+     * @param u
-     * @throws DimensionMismatchException if the dimension of the control
+     *            the control vector
-     * vector does not fit
+     * @throws DimensionMismatchException
+     *             if the dimension of the control vector does not match
      */
-    public void predict(final RealVector u) {
+    public void predict(final RealVector u) throws DimensionMismatchException {
         // sanity checks
         if (u != null &&
             u.getDimension() != controlMatrix.getColumnDimension()) {
@@ -317,26 +320,35 @@ public class KalmanFilter {
     /**
      * Correct the current state estimate with an actual measurement.
      *
-     * @param z the measurement vector
+     * @param z
+     *            the measurement vector
+     * @throws NullArgumentException
+     *             if the measurement vector is {@code null}
      * @throws DimensionMismatchException
      *             if the dimension of the measurement vector does not fit
-     * @throws org.apache.commons.math3.linear.SingularMatrixException
+     * @throws SingularMatrixException
      *             if the covariance matrix could not be inverted
      */
-    public void correct(final double[] z) {
+    public void correct(final double[] z)
+            throws NullArgumentException, DimensionMismatchException, SingularMatrixException {
         correct(new ArrayRealVector(z));
     }
 
     /**
      * Correct the current state estimate with an actual measurement.
      *
-     * @param z the measurement vector
+     * @param z
-     * @throws DimensionMismatchException if the dimension of the
+     *            the measurement vector
-     * measurement vector does not fit
+     * @throws NullArgumentException
-     * @throws org.apache.commons.math3.linear.SingularMatrixException
+     *             if the measurement vector is {@code null}
+     * @throws DimensionMismatchException
+     *             if the dimension of the measurement vector does not fit
+     * @throws SingularMatrixException
      *             if the covariance matrix could not be inverted
      */
-    public void correct(final RealVector z) {
+    public void correct(final RealVector z)
+            throws NullArgumentException, DimensionMismatchException, SingularMatrixException {
+
         // sanity checks
         MathUtils.checkNotNull(z);
         if (z.getDimension() != measurementMatrix.getRowDimension()) {

src/main/java/org/apache/commons/math3/filter/MeasurementModel.java

@@ -33,10 +33,9 @@ public interface MeasurementModel {
     RealMatrix getMeasurementMatrix();
 
     /**
-     * Returns the measurement noise matrix. This method is called by the
+     * Returns the measurement noise matrix. This method is called by the {@link KalmanFilter} every
-     * {@link KalmanFilter} every correct step, so implementations of this
+     * correction step, so implementations of this interface may return a modified measurement noise
-     * interface may return a modified measurement noise depending on current
+     * depending on the current iteration step.
-     * iteration step.
      *
      * @return the measurement noise matrix
      * @see KalmanFilter#correct(double[])

src/main/java/org/apache/commons/math3/filter/ProcessModel.java

@@ -41,10 +41,9 @@ public interface ProcessModel {
     RealMatrix getControlMatrix();
 
     /**
-     * Returns the process noise matrix. This method is called by the
+     * Returns the process noise matrix. This method is called by the {@link KalmanFilter} every
-     * {@link KalmanFilter} every predict step, so implementations of this
+     * prediction step, so implementations of this interface may return a modified process noise
-     * interface may return a modified process noise depending on current
+     * depending on the current iteration step.
-     * iteration step.
      *
      * @return the process noise matrix
      * @see KalmanFilter#predict()
@@ -56,9 +55,8 @@ public interface ProcessModel {
     /**
      * Returns the initial state estimation vector.
      * <p>
-     * Note: if the return value is zero, the Kalman filter will initialize the
+     * <b>Note:</b> if the return value is zero, the Kalman filter will initialize the
      * state estimation with a zero vector.
-     * </p>
      *
      * @return the initial state estimation vector
      */
@@ -67,9 +65,8 @@ public interface ProcessModel {
     /**
      * Returns the initial error covariance matrix.
      * <p>
-     * Note: if the return value is zero, the Kalman filter will initialize the
+     * <b>Note:</b> if the return value is zero, the Kalman filter will initialize the
      * error covariance with the process noise matrix.
-     * </p>
      *
      * @return the initial error covariance matrix
      */