Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Thomas Neidhart 2012-09-05 20:06:07 +00:00
parent 5082325771
commit 86321681e7
5 changed files with 120 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
src/main/java/org/apache/commons/math3/filter/DefaultMeasurementModel.java
View File

@ -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
* {@link KalmanFilter}.
* Default implementation of a {@link MeasurementModel} for the use with a {@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
* parameters for the respective measurement matrix and noise.
* Create a new {@link MeasurementModel}, taking double arrays as input parameters for the
* respective measurement matrix and noise.
*
* @param measMatrix the measurement matrix
* @param measNoise the measurement noise matrix
* @param measMatrix
* 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));
}

84
src/main/java/org/apache/commons/math3/filter/DefaultProcessModel.java
View File

@ -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
* {@link KalmanFilter}.
* Default implementation of a {@link ProcessModel} for the use with a {@link KalmanFilter}.
*
* @since 3.0
* @version $Id$
*/
public class DefaultProcessModel implements ProcessModel {
/**
* The state transition matrix, used to advance the internal state
* estimation each time-step.
* The state transition matrix, used to advance the internal state estimation each time-step.
*/
private RealMatrix stateTransitionMatrix;
/**
* The control matrix, used to integrate a control input into the state
* estimation.
* The control matrix, used to integrate a control input into the state 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
* parameters.
* Create a new {@link ProcessModel}, taking double arrays as input parameters.
*
* @param stateTransition the state transition matrix
* @param control the control matrix
* @param processNoise the process noise matrix
* @param initialStateEstimate the initial state estimate vector
* @param initialErrorCovariance the initial error covariance matrix
* @param stateTransition
* the state transition matrix
* @param control
* the control 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
* parameters. The initial state estimate and error covariance are omitted
* and will be initialized by the {@link KalmanFilter} to default values.
* Create a new {@link ProcessModel}, taking double arrays as input parameters.
* <p>
* 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 control the control matrix
* @param processNoise the process noise matrix
* @param stateTransition
* the state transition 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
* parameters.
* Create a new {@link ProcessModel}, taking double arrays as input parameters.
*
* @param stateTransition the state transition matrix
* @param control the control matrix
* @param processNoise the process noise matrix
* @param initialStateEstimate the initial state estimate vector
* @param initialErrorCovariance the initial error covariance matrix
* @param stateTransition
* the state transition matrix
* @param control
* the control 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,

64
src/main/java/org/apache/commons/math3/filter/KalmanFilter.java
View File

@ -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
* if any of the given inputs is null (except for the control
* matrix)
* @throws NullArgumentException
* if any of the given inputs is null (except for the control 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,
final MeasurementModel measurement) {
public KalmanFilter(final ProcessModel process, 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 =
new ArrayRealVector(transitionMatrix.getColumnDimension());
stateEstimation = 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
* @throws DimensionMismatchException if the dimension of the control
* vector does not fit
* @param u
* the control vector
* @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
* if the covariance matrix could not be inverted
* if the dimension of the measurement vector does not fit
* @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
* @throws DimensionMismatchException if the dimension of the
* measurement vector does not fit
* @throws org.apache.commons.math3.linear.SingularMatrixException
* if the covariance matrix could not be inverted
* @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 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()) {

7
src/main/java/org/apache/commons/math3/filter/MeasurementModel.java
View File

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

13
src/main/java/org/apache/commons/math3/filter/ProcessModel.java
View File

@ -41,10 +41,9 @@ public interface ProcessModel {
RealMatrix getControlMatrix();
/**
* Returns the process noise matrix. This method is called by the
* {@link KalmanFilter} every predict step, so implementations of this
* interface may return a modified process noise depending on current
* iteration step.
* Returns the process noise matrix. This method is called by the {@link KalmanFilter} every
* prediction step, so implementations of this interface may return a modified process noise
* depending on the current 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
*/