NEWS

Changes in Nonlinear Estimation Toolbox 2.0.1
=============================================

* Set compiler flags for MacOS X in compileMexOpenMP() correctly.
* Added a Mac OS X GLCD MEX file. This means that the LCD-based Gaussian sampling technique (GaussianSamplingLCD) and the
  estimators using it (S2KF, S2RUF, and PGF) now also work out of the box on Mac OS X.
* The dimension of a new system state is now set in Filter.setState() before the code of a subclass is executed.
  Thus, obj.dimState can now be used correctly when setting the system state.
* Added several MEX file examples for system models, measurement models, likelihoods, and their parallelization with OpenMP.
* Minor code cleanups.


Changes in Nonlinear Estimation Toolbox 2.0
=============================================

This is a major toolbox release for cleaning up its API (more consistent method naming and removal of rather unnecessary
functionalities) to allow for a better API understanding and better implementation of new features. This release also
includes new estimators.

* General changes:
  - Filters now only handle the case of a single measurement. For example, Kalman filters now only accept a measurement vector,
    not a matrix of multiple measurements. However, processing multiple measurements can still be done by stacking measurements
    to a vector.
  - Measurement models can now only generate a single measurement with the simulate() method.
  - Likelihood-based filters now accept any type of measurement data, not only real-valued measurement vectors as it is the case
    for Kalman filters. That is, you can pass, for example, a cell array of data that is required by the likelihood function.
  - Various class methods are now sealed to prevent unintended overwriting.
  - Added new subfolders for a better structuring toolbox files. You may have to update your Matlab PATH accordingly.

* Filters:
  - Renamed getPointEstimate() to getStateMeanAndCov().
  - In addition to getPointEstimate(), getStateMeanAndCov() now also returns the square root of the system state covariance
    matrix (the lower Cholesky decomposition) analogous to the getMeanAndCov() methods of probability distributions.
  - Added setStateMeanAndCov() method for fastly setting the system state without creating a temporary Gaussian distribution,
    e.g., in order to assign the Gaussian state estimate of a filter to another one. Note that this method does not perform
    input validation like setState()!
  - Gaussian filters:
    * Users can now specify custom state estimate post processing via the {set,get}PredictionPostProcessing()
      and {set,get}setUpdatePostProcessing() methods, e.g., to implement constrained state estimation. The set post processing
      methods are then executed after each state prediction and measurement update, respectively.
  - Added several recursive update filter (RUF) variants:
    * ERUF: extended recursive update filter  (the originally proposed RUF).
    * CRUF: the fifth-degree cubature recursive update filter.
    * GHRUF: the Gauss-Hermite recursive update filter.
    * RURUF: the randomized unscented recursive update filter.
    * S2RUF: the smart sampling recursive update filter.
    * URUF: the unscented recursive update filter.
  - Iterative Kalman filters:
    * Dropped the analytic moment computation models used by Kalman filters and moved the analytic moment computation for the
      linear cases directly into LinearMeasurementModel and LinearSystemModel by introducing the getAnalyticMoments() methods.
    * Users can now specify a custom convergence check via the {set,get}ConvergenceCheck() methods, e.g., based on the
      Kullback-Leibler divergence (KLD) using the new Utils.getGaussianKLD() method.
    * Added getNumIterations().
    * Renamed setMeasValidationThreshold() to setMeasGatingThreshold().
    * Renamed getMeasValidationThreshold() to getMeasGatingThreshold().
    * Removed getLastUpdateData().
    * Removed the now obsolete AnalyticKF filter.
    * The implementation of a sample-based Kalman filter now handles the special case of equally weighted samples efficiently.
      That is, there is no need for a specialized implementation, e.g., for the S2KF or the UKF with equally weighted samples.
      This also holds for the new sample-based recursive update filters.
    * RUKF:
      - Renamed setNumIterations() to setNumSamplesFactors.
      - Renamed getNumIterations() to getNumSamplesFactors.
    * S2KF:
      - The used LCD-based Gaussian sampling technique can now be configured completely independently for state prediction and
        measurement update.
      - Added getNumSamplesConfigPrediction().
      - Added getNumSamplesConfigUpdate().
      - Renamed setNumSamplesByFactor() to setNumSamplesByFactors().
      - Removed online computation mode including the setOnlineMode() method.
      - Removed asymmetric LCD-based sampling mode including the setSymmetricMode() method.
    * UKF:
      - Renamed setSampleScaling() to setSampleScalings().
      - Renamed getSampleScaling() to getSampleScalings().
  - Particle filters:
    * Changed default name of SIRPF from "SIR-PF" to "SIRPF".
    * Changed default name of ASIRPF from "Auxiliary SIR-PF" to "ASIRPF".
    * Merged the PF interface into the SIRPF.
  - PGF:
    * The used LCD-based Gaussian sampling technique can now be configured completely independently for state prediction and
      measurement update.
    * Added getNumSamplesConfigPrediction().
    * Added getNumSamplesConfigUpdate().
    * Renamed setNumSamplesByFactor() to setNumSamplesByFactors().
    * Renamed getLastUpdateData() to getNumProgSteps().

* Distributions:
  - All probability distributions now have a set() method. That is, a distribution can be modified after its creation.
  - All default constructors now return an uninitialized distribution.
  - Renamed getDimension() to getDim().
  - Renamed getMeanAndCovariance() to getMeanAndCov().
  - Removed the JointDistribution.
  - DiracMixture:
    * Added check for invalid covariance matrix when trying to compute its square root in getMeanAndCov().

* Gaussian sampling techniques:
  - The getStdNormalSamples() and getSamples() methods of all Gaussian sampling techniques now return a single scalar weight in
    case of equally weighted samples in order to efficiently handle the computation of sample-based moments, e.g., means or
    covariance matrices in Kalman filtering.
  - GaussianSamplingRnd:
    * Now uses a default number of 1,000 particles instead of only 100.
  - GaussianSamplingLCD:
    * Added getSymmetricMode().
    * Added getNumSamplesConfig().
    * Removed online computation mode including the setOnlineMode() method.

* Misc:
  - FilterSet:
    * Renamed getPointEstimates() to getStatesMeanAndCov().
    * In addition to getPointEstimates(), getStatesMeanAndCov() now also returns the square roots of the system state covariance
      matrices (the lower Cholesky decomposition) analogous to the Filter's getStateMeanAndCov() method.
    * Added setStatesMeanAndCov() method for fastly setting the system state of all filters without creating a temporary Gaussian 
      distribution, e.g., in order to assign the Gaussian state estimate of a filter to another one. Note that this method does 
      not perform input validation like setStates()!
  - Utilities:
    * Utils.getMeanAndCov() now handles the case of a single scalar weight in case of equally weighted samples (in order to
      smoothly work with the changed weights of the Gaussian sampling techniques).
    * Utils.kalmanUpdate() now additionally returns the squared Mahalanobis distance of the measurement vector.
    * Added Utils.getGMMeanAndCov() for computing mean and covariance matrix of a Gaussian mixture distribution.
    * Added Utils.getGaussianKLD() for computing the Gaussian Kullback-Leibler divergence (KLD).
    * Added Utils.getGaussianL2Distance() for computing the Gaussian L2 distance.
    * Removed Utils.baseBlockDiag().
    * Removed Utils.getMeanCovAndCrossCov().
    * Removed Utils.getStateSamples().
    * Removed Utils.getStateNoiseSamples().
  - Updated Eigen linear algebra library to version 3.3.4.

* Interfaces:
  - Added LinearGaussianFilter.
  - Added FirstOrderTaylorLinearGaussianFilter.
  - Added SecondOrderTaylorLinearGaussianFilter.
  - Added SampleBasedLinearGaussianFilter.
  - Added CubatureLinearGaussianFilter.
  - Added GaussHermiteLinearGaussianFilter.
  - Added RandomizedUnscentedLinearGaussianFilter.
  - Added SmartSamplingLinearGaussianFilter.
  - Added UnscentedLinearGaussianFilter.
  - Added IterativeKalmanFilter.
  - Added RecursiveUpdateFilter.
  - Added SampleBasedIterativeKalmanFilter.
  - Added SampleBasedRecursiveUpdateFilter.
  - Renamed BasePF to ParticleFilter.
  - Removed AnalyticMeasurementModel.
  - Removed AnalyticSystemModel.
  - Removed FOTaylorBasedJointlyGaussianPrediction.
  - Removed SOTaylorBasedJointlyGaussianPrediction.
  - Removed SampleBasedJointlyGaussianPrediction.
  - Removed KF.
  - Removed LRKF.

* Examples:
  - Updated all "getting started" examples to the new API, changed the used nonlinear system model, and introduced more detailed
    evaluation plots in the "complete estimation example".
  - Added examples for all probability distributions.
  - Added examples for all measurement models.
  - Added examples for all system models.

* Tests:
  - Added unit tests for all Gaussian sampling techniques.
  - Added unit tests for nearly all existing filters.
  - Added unit tests for all new recursive update filter variants.
  - Added unit tests for all probability distributions.
  - The general structure for filter unit tests was overhauled.


Changes in Nonlinear Estimation Toolbox 1.5.1
=============================================

* Fixed unnecessary computation of Hessians in MeasurementModel and MixedNoiseMeasurementModel if only Jacobians are requested.
* The PGF now overwrites the moment computations for the state prediction in order to exploit the fact
  that all samples used by the LCD-based Gaussian sampling technique are equally weighted.
* Moved predictedMomentsMixedNoise() implementation to GaussianFilter in order to avoid unnecessary code duplication.
* New and improved unit tests.
* Updated Eigen linear algebra library to version 3.3.3.
* Various code cleanups and documentation improvements.


Changes in Nonlinear Estimation Toolbox 1.5
=============================================

* Added the regularized particle filter (class RPF).
* The UKF uses individual sample scalings for prediction and update.
* The GHKF uses individual number of quadrature points for prediction and update.
* The S2KF now overwrites the moment computations for the state prediction and the measurement update in order to exploit
  the fact that all samples used by the S²KF are equally weighted. This reduces runtime and has numerical benefits.
* The LCD-based Gaussian sampling now uses different bMax for different dimensions by default.
* Analogous to the SampleBasedJointlyGaussianPrediction interface, the FOTaylorBasedJointlyGaussianPrediction and
  SOTaylorBasedJointlyGaussianPrediction interfaces are added to separate the first-order and second-order Taylor series
  based prediction from the EKF and EKF2, respectively.
* State covariance matrices of Gaussian filters are now guaranteed to be symmetric.
  This includes:
    - LinearSystemModel.analyticPredictedMoments() guarantees a symmetric predicted state covariance matrix.
    - LinearMeasurementModel.analyticMeasurementMoments() guarantees a symmetric measurement covariance matrix.
    - Utils.getMeanAndCov() and Utils.getMeanCovAndCrossCov() guarantees a symmetric measurement covariance matrix
      in case of non-equally weighted samples.
    - Utils.decomposedStateUpdate() guarantees a symmetric posterior covariance matrix.
      Note that Utils.decomposedStateUpdate() now additionally requires the square root of the prior covariance matrix
      and the square root of the already updated state covariance matrix.
* Refactoring of the GaussianFilter measurement updates: the GaussianFilter class now handles the state decomposition.
  As a consquence, subclasses of GaussianFilter now have to implement performUpdateObservable() rather than performUpdate().
* All GaussianSampling subclasses can now be copied.
* Although the Filter class already inherits from matlab.mixin.Copyable, not all implemented filters could be correctly copied
  (in particular filters that inherit from LRKF). This is now fixed. Using the copy() method, for example,
  Gaussian mixture estimators can now be easily created by configuring a GaussianFilter subclass (e.g., select number of
  samples in the S²KF) and copy it several times to get an identical filter instance for each Gaussian mixture component.
* In addition, the Filter.copyWithName() method is introduced to be able to give the copied filter instance a different name.
  The standard copy() method also copies the name of the filter instance to be copied. However, a filter cannot change its
  name after construction. If it is desired to have different names for different copies of a filter instance, use this
  method to select proper names during the copy procedure, e.g., to put several copies of a filter instance in the same
  FilterSet (which requires the filters to have different names to allow for a unique identification).
* GaussianMixture.drawRndSamples() now additionally returns for each sample the ID of its corresponding component.
* New and improved unit tests.
* Various code cleanups and documentation improvements.
* When compiling MEX files with compileMexOpenMP(), OpenMP is disabled by default on Mac OS.
* Updated Eigen linear algebra library to version 3.3.1


Changes in Nonlinear Estimation Toolbox 1.4
=============================================

* Added the second-order EKF (EKF2). This also includes its iterated version (analogous to the iterated EKF).
* The derivative() methods of all system models and measurement models now additionally return the Hessians (required for EKF2). By default, the Hessians are computed using central finite differences.
* Utils.diffQuotientState() and Utils.diffQuotientStateAndNoise() now additionally compute approximative Hessian matrices using central finite differences. This also changes the Jacobian approximation from forward finite differences to central finite differences.
* Updated Eigen to version 3.2.10.
* Various code cleanups.

* Bugs fixed
  - #4    Please add second order EKF.


Changes in Nonlinear Estimation Toolbox 1.3
=============================================

* All subclasses of GaussianFilter can now perform a semi-analytic filter step by using a state decomposition.
  That is, if the considered measurement model/likelihood function does not depend upon the entire system state,
  the update of the non-dependent state variables can be performed in closed-form. It can be enabled with the
  GaussianFilter.setStateDecompDim() method. Currently it is available for all subclasses of KF (AnalyticKF, CKF,
  EKF, GHKF, RUKF, S2KF, UKF), the PGF, and the GPF.
* The UKF Gaussian sampling can now be configured such that the weight of the mean sample is negative.
* Updated Eigen to version 3.2.9.
* The state prediction for subclasses of GaussianFilter was massively refactored to improve code reuse and code
  quality. As a side effect, the EKF can now work with AnalyticSystemModels. Moreover, the interface
  SampleBasedGaussianFilter was removed and the interface SampleBasedJointlyGaussianPrediction added. Subclasses of
  GaussianFilter now have to implement the predictedMoments*() methods.
* The KF measurement update was massively refactored to improve code reuse and code quality. As a side effect,
  the EKF can now work with AnalyticMeasurementModels. Subclasses of KF now have to implement the getMomentFunc*()
  methods.
* Fixed a bug when evaluating the logarithmic PDF of a Gaussian mixture consisting only of a single component.


Changes in Nonlinear Estimation Toolbox 1.2.1
=============================================

* Minor bug fixes
* Some refactoring of Kalman filter code
* Updated Eigen to version 3.2.8
* Implemented analytic derivatives for linear models
* Added unit tests for model derivatives


Changes in Nonlinear Estimation Toolbox 1.2
=============================================

* Unified naming scheme in error messages for supported system models and measurement models
* Fixed bug in PF: number of particles was not updated when setting the system state with a DiracMixture
* Moved the resamling step of SIRPF and ASIRPF from the end of the measurement update to the beginning of predict(), update(), and step() to obtain more accurate point estimates
* Default compiler flags in compileMex() function are now also set when compiling on Mac OS
* Added compileMexOpenMP() function that automatically enables OpenMP when compiling a MEX file
* Fixed some warnings in C++ code
* Updated the Eigen linear algebra library to version 3.2.7
* Enabled OpenMP when computing Gaussian LCD samples
* Set default bMax value to 200 when computing Gaussian LCD samples
* Updated GLCD MEX files for Windows and Linux


Changes in Nonlinear Estimation Toolbox 1.1
=============================================

* Added a Filter.step() method in order to perform combined time and measurement updates
* Added also a FilterSet.step() method
* Added new abstract base class BasePF for particle filters
* Added a Gaussian Particle Filter with combined time and measurement update (CGPF)
* Added the Auxiliary SIR Particle Filter (ASIRPF)
* Added unit tests for CGPF
* Added unit tests for ASIRPF
* Added unit tests for the GaussianFilter, SampleBasedGaussianFilter, KF, LRKF, and PF interfaces
* Added missing additive noise dimensionality checks to GPF the when dealing with AdditiveNoiseSystemModel or MixedNoiseSystemModel
* For better code reuse and reliability, EnKF, SIRPF, ASIRPF, and CGPF now use the same code for state predictions, and SIRPF and GPF the same code for likelihood evaluations
* Improved the numerical stability of the GaussianMixture logarithmic pdf
* Utils.resampling() and Utils.systematicResampling() now additionally return the indices of the samples that were resampled from
* Updated the Eigen linear algebra library to version 3.2.6
* Fixed bug in UKF.getSampleScaling()
* Fixed bug in L-BFGS C++ code
* Fixed bug in GPF unit test
* Updated GLCD MEX files for Windows and Linux
* Various code cleanups

* Bugs fixed
  - #3    Add the Auxiliary SIR Particle Filter to the toolbox
  
  
Changes in Nonlinear Estimation Toolbox 1.0.2
=============================================

* Bugs fixed
  - #5    Better handle errors related to the GLCD MEX files


Changes in Nonlinear Estimation Toolbox 1.0.1
=============================================

* Added unit tests for
  - SIRPF.SIRPF()
  - SIRPF.setState()
  - SIRPF.getPointEstimate()
  - Utils.rndOrthogonalMatrix()
  - Utils.getStateSamples()
  - Utils.getStateNoiseSamples()
  
* Bugs fixed
  - #1    SIRPF cannot handle DiracMixture distributions when setting the system state
  - #2    Inconsistent behavior when creating DiracMixture distributions


Changes in Nonlinear Estimation Toolbox 1.0
=============================================

First toolbox release containing

* Filters
  - AnalyticKF
  - CKF
  - EKF
  - EnKF
  - GHKF
  - GPF
  - PGF
  - RUKF
  - S2KF
  - SIRPF
  - UKF
  
* Distributions
  - DiracMixture
  - Gaussian
  - GaussianMixture
  - JointDistribution
  - Uniform
  
* Gaussian Sampling Techniques
  - GaussianSamplingCKF
  - GaussianSamplingGHQ
  - GaussianSamplingLCD
  - GaussianSamplingRnd
  - GaussianSamplingRUKF
  - GaussianSamplingUKF
  
* System Models
  - AdditiveNoiseSystemModel
  - AnalyticSystemModel
  - MixedNoiseSystemModel
  - SystemModel
  - LinearSystemModel
  
* Measurement Models
  - AdditiveNoiseMeasurementModel
  - AnalyticMeasurementModel
  - Likelihood
  - MeasurementModel
  - MixedNoiseMeasurementModel
  - LinearMeasurementModel