1   /* Copyright 2002-2024 CS GROUP
2    * Licensed to CS GROUP (CS) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * CS licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *   http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.orekit.estimation.sequential;
18  
19  import java.util.Collections;
20  import java.util.List;
21  
22  import org.hipparchus.filtering.kalman.unscented.UnscentedKalmanFilter;
23  import org.hipparchus.linear.MatrixDecomposer;
24  import org.hipparchus.util.UnscentedTransformProvider;
25  import org.orekit.estimation.measurements.ObservedMeasurement;
26  import org.orekit.propagation.conversion.DSSTPropagatorBuilder;
27  import org.orekit.propagation.semianalytical.dsst.DSSTPropagator;
28  import org.orekit.utils.ParameterDriver;
29  import org.orekit.utils.ParameterDriversList;
30  
31  /**
32   * Implementation of an Unscented Semi-analytical Kalman filter (USKF) to perform orbit determination.
33   * <p>
34   * The filter uses a {@link DSSTPropagatorBuilder}.
35   * </p>
36   * <p>
37   * The estimated parameters are driven by {@link ParameterDriver} objects. They are of 3 different types:<ol>
38   *   <li><b>Orbital parameters</b>:The position and velocity of the spacecraft, or, more generally, its orbit.<br>
39   *       These parameters are retrieved from the reference trajectory propagator builder when the filter is initialized.</li>
40   *   <li><b>Propagation parameters</b>: Some parameters modeling physical processes (SRP or drag coefficients etc...).<br>
41   *       They are also retrieved from the propagator builder during the initialization phase.</li>
42   *   <li><b>Measurements parameters</b>: Parameters related to measurements (station biases, positions etc...).<br>
43   *       They are passed down to the filter in its constructor.</li>
44   * </ol>
45   * <p>
46   * The Kalman filter implementation used is provided by the underlying mathematical library Hipparchus.
47   * All the variables seen by Hipparchus (states, covariances...) are normalized
48   * using a specific scale for each estimated parameters or standard deviation noise for each measurement components.
49   * </p>
50   *
51   * <p>An {@link SemiAnalyticalUnscentedKalmanEstimator} object is built using the {@link SemiAnalyticalUnscentedKalmanEstimatorBuilder#build() build}
52   * method of a {@link SemiAnalyticalUnscentedKalmanEstimatorBuilder}.</p>
53   *
54   * @author Gaëtan Pierre
55   * @author Bryan Cazabonne
56   * @since 11.3
57   */
58  public class SemiAnalyticalUnscentedKalmanEstimator extends AbstractKalmanEstimator {
59  
60      /** Unscented Kalman filter process model. */
61      private final SemiAnalyticalUnscentedKalmanModel processModel;
62  
63      /** Filter. */
64      private final UnscentedKalmanFilter<MeasurementDecorator> filter;
65  
66      /** Unscented Kalman filter estimator constructor (package private).
67       * @param decomposer decomposer to use for the correction phase
68       * @param propagatorBuilder propagator builder used to evaluate the orbit.
69       * @param processNoiseMatricesProvider provider for process noise matrix
70       * @param estimatedMeasurementParameters measurement parameters to estimate
71       * @param measurementProcessNoiseMatrix provider for measurement process noise matrix
72       * @param utProvider provider for the unscented transform
73       */
74      SemiAnalyticalUnscentedKalmanEstimator(final MatrixDecomposer decomposer,
75                                             final DSSTPropagatorBuilder propagatorBuilder,
76                                             final CovarianceMatrixProvider processNoiseMatricesProvider,
77                                             final ParameterDriversList estimatedMeasurementParameters,
78                                             final CovarianceMatrixProvider measurementProcessNoiseMatrix,
79                                             final UnscentedTransformProvider utProvider) {
80          super(Collections.singletonList(propagatorBuilder));
81          // Build the process model and measurement model
82          this.processModel = new SemiAnalyticalUnscentedKalmanModel(propagatorBuilder, processNoiseMatricesProvider,
83                                                                     estimatedMeasurementParameters, measurementProcessNoiseMatrix);
84  
85          // Unscented Kalman Filter of Hipparchus
86          this.filter = new UnscentedKalmanFilter<>(decomposer, processModel, processModel.getEstimate(), utProvider);
87  
88      }
89  
90      /** {@inheritDoc}. */
91      @Override
92      protected KalmanEstimation getKalmanEstimation() {
93          return processModel;
94      }
95  
96      /** Set the observer.
97       * @param observer the observer
98       */
99      public void setObserver(final KalmanObserver observer) {
100         this.processModel.setObserver(observer);
101     }
102 
103     /** Process a single measurement.
104      * <p>
105      * Update the filter with the new measurement by calling the estimate method.
106      * </p>
107      * @param observedMeasurements the list of measurements to process
108      * @return estimated propagators
109      */
110     public DSSTPropagator processMeasurements(final List<ObservedMeasurement<?>> observedMeasurements) {
111         return processModel.processMeasurements(observedMeasurements, filter);
112     }
113 
114 }
115