1 /* Copyright 2002-2025 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 org.hipparchus.linear.MatrixDecomposer;
20 import org.hipparchus.linear.QRDecomposer;
21 import org.hipparchus.util.UnscentedTransformProvider;
22 import org.orekit.errors.OrekitException;
23 import org.orekit.errors.OrekitMessages;
24 import org.orekit.propagation.conversion.DSSTPropagatorBuilder;
25 import org.orekit.utils.ParameterDriversList;
26
27 /** Builder for an Unscented Semi-analytical Kalman filter estimator.
28 * @author Gaëtan Pierre
29 * @author Bryan Cazabonne
30 * @since 11.3
31 */
32 public class SemiAnalyticalUnscentedKalmanEstimatorBuilder {
33
34 /** Decomposer to use for the correction phase. */
35 private MatrixDecomposer decomposer;
36
37 /** Builders for propagator. */
38 private DSSTPropagatorBuilder propagatorBuilder;
39
40 /** Estimated measurements parameters. */
41 private ParameterDriversList estimatedMeasurementsParameters;
42
43 /** Process noise matrix provider. */
44 private CovarianceMatrixProvider processNoiseMatrixProvider;
45
46 /** Process noise matrix provider for measurement parameters. */
47 private CovarianceMatrixProvider measurementProcessNoiseMatrix;
48
49 /** Unscend transform provider. */
50 private UnscentedTransformProvider utProvider;
51
52 /** Default constructor.
53 * Set an Unscented Semi-analytical Kalman filter.
54 */
55 public SemiAnalyticalUnscentedKalmanEstimatorBuilder() {
56 this.decomposer = new QRDecomposer(1.0e-15);
57 this.propagatorBuilder = null;
58 this.estimatedMeasurementsParameters = new ParameterDriversList();
59 this.processNoiseMatrixProvider = null;
60 this.measurementProcessNoiseMatrix = null;
61 this.utProvider = null;
62 }
63
64 /** Construct a {@link SemiAnalyticalUnscentedKalmanEstimator} from the data in this builder.
65 * <p>
66 * Before this method is called, {@link #addPropagationConfiguration(DSSTPropagatorBuilder,
67 * CovarianceMatrixProvider) addPropagationConfiguration()} must have been called
68 * at least once, otherwise configuration is incomplete and an exception will be raised.
69 * <p>
70 * In addition, the {@link #unscentedTransformProvider(UnscentedTransformProvider)
71 * unscentedTransformProvider()} must be called to configure the unscented transform
72 * provider use during the estimation process, otherwise configuration is
73 * incomplete and an exception will be raised.
74 * </p>
75 * @return a new {@link SemiAnalyticalUnscentedKalmanEstimator}.
76 */
77 public SemiAnalyticalUnscentedKalmanEstimator build() {
78 if (propagatorBuilder == null) {
79 throw new OrekitException(OrekitMessages.NO_PROPAGATOR_CONFIGURED);
80 }
81 if (utProvider == null) {
82 throw new OrekitException(OrekitMessages.NO_UNSCENTED_TRANSFORM_CONFIGURED);
83 }
84 return new SemiAnalyticalUnscentedKalmanEstimator(decomposer, propagatorBuilder, processNoiseMatrixProvider,
85 estimatedMeasurementsParameters, measurementProcessNoiseMatrix,
86 utProvider);
87 }
88
89 /** Configure the matrix decomposer.
90 * @param matrixDecomposer decomposer to use for the correction phase
91 * @return this object.
92 */
93 public SemiAnalyticalUnscentedKalmanEstimatorBuilder decomposer(final MatrixDecomposer matrixDecomposer) {
94 decomposer = matrixDecomposer;
95 return this;
96 }
97
98 /** Configure the unscented transform provider.
99 * @param transformProvider unscented transform to use for the prediction phase
100 * @return this object.
101 */
102 public SemiAnalyticalUnscentedKalmanEstimatorBuilder unscentedTransformProvider(final UnscentedTransformProvider transformProvider) {
103 this.utProvider = transformProvider;
104 return this;
105 }
106
107 /** Add a propagation configuration.
108 * <p>
109 * This method must be called once initialize the propagator builder
110 * used by the Semi-Analytical Unscented Kalman Filter.
111 * </p>
112 * @param builder The propagator builder to use in the Kalman filter.
113 * @param provider The process noise matrices provider to use, consistent with the builder.
114 * @return this object.
115 */
116 public SemiAnalyticalUnscentedKalmanEstimatorBuilder addPropagationConfiguration(final DSSTPropagatorBuilder builder,
117 final CovarianceMatrixProvider provider) {
118 propagatorBuilder = builder;
119 processNoiseMatrixProvider = provider;
120 return this;
121 }
122
123 /** Configure the estimated measurement parameters.
124 * <p>
125 * If this method is not called, no measurement parameters will be estimated.
126 * </p>
127 * @param estimatedMeasurementsParams The estimated measurements' parameters list.
128 * @param provider covariance matrix provider for the estimated measurement parameters
129 * @return this object.
130 */
131 public SemiAnalyticalUnscentedKalmanEstimatorBuilder estimatedMeasurementsParameters(final ParameterDriversList estimatedMeasurementsParams,
132 final CovarianceMatrixProvider provider) {
133 estimatedMeasurementsParameters = estimatedMeasurementsParams;
134 measurementProcessNoiseMatrix = provider;
135 return this;
136 }
137
138 }