001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.math3.filter;
018    
019    import org.apache.commons.math3.exception.DimensionMismatchException;
020    import org.apache.commons.math3.exception.NoDataException;
021    import org.apache.commons.math3.exception.NullArgumentException;
022    import org.apache.commons.math3.linear.Array2DRowRealMatrix;
023    import org.apache.commons.math3.linear.ArrayRealVector;
024    import org.apache.commons.math3.linear.RealMatrix;
025    import org.apache.commons.math3.linear.RealVector;
026    
027    /**
028     * Default implementation of a {@link ProcessModel} for the use with a {@link KalmanFilter}.
029     *
030     * @since 3.0
031     * @version $Id: DefaultProcessModel.java 1416643 2012-12-03 19:37:14Z tn $
032     */
033    public class DefaultProcessModel implements ProcessModel {
034        /**
035         * The state transition matrix, used to advance the internal state estimation each time-step.
036         */
037        private RealMatrix stateTransitionMatrix;
038    
039        /**
040         * The control matrix, used to integrate a control input into the state estimation.
041         */
042        private RealMatrix controlMatrix;
043    
044        /** The process noise covariance matrix. */
045        private RealMatrix processNoiseCovMatrix;
046    
047        /** The initial state estimation of the observed process. */
048        private RealVector initialStateEstimateVector;
049    
050        /** The initial error covariance matrix of the observed process. */
051        private RealMatrix initialErrorCovMatrix;
052    
053        /**
054         * Create a new {@link ProcessModel}, taking double arrays as input parameters.
055         *
056         * @param stateTransition
057         *            the state transition matrix
058         * @param control
059         *            the control matrix
060         * @param processNoise
061         *            the process noise matrix
062         * @param initialStateEstimate
063         *            the initial state estimate vector
064         * @param initialErrorCovariance
065         *            the initial error covariance matrix
066         * @throws NullArgumentException
067         *             if any of the input arrays is {@code null}
068         * @throws NoDataException
069         *             if any row / column dimension of the input matrices is zero
070         * @throws DimensionMismatchException
071         *             if any of the input matrices is non-rectangular
072         */
073        public DefaultProcessModel(final double[][] stateTransition,
074                                   final double[][] control,
075                                   final double[][] processNoise,
076                                   final double[] initialStateEstimate,
077                                   final double[][] initialErrorCovariance)
078                throws NullArgumentException, NoDataException, DimensionMismatchException {
079    
080            this(new Array2DRowRealMatrix(stateTransition),
081                    new Array2DRowRealMatrix(control),
082                    new Array2DRowRealMatrix(processNoise),
083                    new ArrayRealVector(initialStateEstimate),
084                    new Array2DRowRealMatrix(initialErrorCovariance));
085        }
086    
087        /**
088         * Create a new {@link ProcessModel}, taking double arrays as input parameters.
089         * <p>
090         * The initial state estimate and error covariance are omitted and will be initialized by the
091         * {@link KalmanFilter} to default values.
092         *
093         * @param stateTransition
094         *            the state transition matrix
095         * @param control
096         *            the control matrix
097         * @param processNoise
098         *            the process noise matrix
099         * @throws NullArgumentException
100         *             if any of the input arrays is {@code null}
101         * @throws NoDataException
102         *             if any row / column dimension of the input matrices is zero
103         * @throws DimensionMismatchException
104         *             if any of the input matrices is non-rectangular
105         */
106        public DefaultProcessModel(final double[][] stateTransition,
107                                   final double[][] control,
108                                   final double[][] processNoise)
109                throws NullArgumentException, NoDataException, DimensionMismatchException {
110    
111            this(new Array2DRowRealMatrix(stateTransition),
112                    new Array2DRowRealMatrix(control),
113                    new Array2DRowRealMatrix(processNoise), null, null);
114        }
115    
116        /**
117         * Create a new {@link ProcessModel}, taking double arrays as input parameters.
118         *
119         * @param stateTransition
120         *            the state transition matrix
121         * @param control
122         *            the control matrix
123         * @param processNoise
124         *            the process noise matrix
125         * @param initialStateEstimate
126         *            the initial state estimate vector
127         * @param initialErrorCovariance
128         *            the initial error covariance matrix
129         */
130        public DefaultProcessModel(final RealMatrix stateTransition,
131                                   final RealMatrix control,
132                                   final RealMatrix processNoise,
133                                   final RealVector initialStateEstimate,
134                                   final RealMatrix initialErrorCovariance) {
135            this.stateTransitionMatrix = stateTransition;
136            this.controlMatrix = control;
137            this.processNoiseCovMatrix = processNoise;
138            this.initialStateEstimateVector = initialStateEstimate;
139            this.initialErrorCovMatrix = initialErrorCovariance;
140        }
141    
142        /** {@inheritDoc} */
143        public RealMatrix getStateTransitionMatrix() {
144            return stateTransitionMatrix;
145        }
146    
147        /** {@inheritDoc} */
148        public RealMatrix getControlMatrix() {
149            return controlMatrix;
150        }
151    
152        /** {@inheritDoc} */
153        public RealMatrix getProcessNoise() {
154            return processNoiseCovMatrix;
155        }
156    
157        /** {@inheritDoc} */
158        public RealVector getInitialStateEstimate() {
159            return initialStateEstimateVector;
160        }
161    
162        /** {@inheritDoc} */
163        public RealMatrix getInitialErrorCovariance() {
164            return initialErrorCovMatrix;
165        }
166    }