    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    }