1   /* Copyright 2002-2021 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.measurements;
18  
19  import java.util.List;
20  
21  import org.orekit.propagation.SpacecraftState;
22  import org.orekit.utils.ParameterDriver;
23  
24  
25  /** Interface for measurements used for orbit determination.
26   * <p>
27   * The most important methods of this interface allow to:
28   * <ul>
29   *   <li>get the observed value,</li>
30   *   <li>estimate the theoretical value of a measurement,</li>
31   *   <li>compute the corresponding partial derivatives (with respect to state and parameters)</li>
32   * </ul>
33   *
34   * <p>
35   * The estimated theoretical values can be modified by registering one or several {@link
36   * EstimationModifier EstimationModifier} objects. These objects will manage notions
37   * like tropospheric delays, biases, ...
38   * </p>
39   * @param <T> the type of the measurement
40   * @author Luc Maisonobe
41   * @since 8.0
42   */
43  public interface ObservedMeasurement<T extends ObservedMeasurement<T>> extends ComparableMeasurement {
44  
45      /** Enable or disable a measurement.
46       * <p>
47       * Disabling a measurement allow to not consider it at
48       * one stage of the orbit determination (for example when
49       * it appears to be an outlier as per current estimated
50       * covariance).
51       * </p>
52       * @param enabled if true the measurement will be enabled,
53       * otherwise it will be disabled
54       */
55      void setEnabled(boolean enabled);
56  
57      /** Check if a measurement is enabled.
58       * @return true if the measurement is enabled
59       */
60      boolean isEnabled();
61  
62      /** Get the dimension of the measurement.
63       * <p>
64       * Dimension is the size of the array containing the
65       * value. It will be one for a scalar measurement like
66       * a range or range-rate, but 6 for a position-velocity
67       * measurement.
68       * </p>
69       * @return dimension of the measurement
70       */
71      int getDimension();
72  
73      /** Get the theoretical standard deviation.
74       * <p>
75       * The theoretical standard deviation is a theoretical value
76       * used for normalizing the residuals. It acts as a weighting
77       * factor to mix appropriately measurements with different units
78       * and different accuracy. The value has the same dimension as
79       * the measurement itself (i.e. when a residual is divided by
80       * this value, it becomes dimensionless).
81       * </p>
82       * @return expected standard deviation
83       * @see #getBaseWeight()
84       */
85      double[] getTheoreticalStandardDeviation();
86  
87      /** Get the base weight associated with the measurement
88       * <p>
89       * The base weight is used on residuals already normalized thanks to
90       * {@link #getTheoreticalStandardDeviation()} to increase or
91       * decrease relative effect of some measurements with respect to
92       * other measurements. It is a dimensionless value, typically between
93       * 0 and 1 (but it can really have any non-negative value).
94       * </p>
95       * @return base weight
96       * @see #getTheoreticalStandardDeviation()
97       */
98      double[] getBaseWeight();
99  
100     /** Add a modifier.
101      * <p>
102      * The modifiers are applied in the order in which they are added in order to
103      * {@link #estimate(int, int, SpacecraftState[]) estimate} the measurement.
104      * </p>
105      * @param modifier modifier to add
106      * @see #getModifiers()
107      */
108     void addModifier(EstimationModifier<T> modifier);
109 
110     /** Get the modifiers that apply to a measurement.
111      * @return modifiers that apply to a measurement
112      * @see #addModifier(EstimationModifier)
113      */
114     List<EstimationModifier<T>> getModifiers();
115 
116     /** Get the drivers for this measurement parameters, including its modifiers parameters.
117      * @return drivers for this measurement parameters, including its modifiers parameters
118      */
119     List<ParameterDriver> getParametersDrivers();
120 
121     /** Get the satellites related to this measurement.
122      * @return satellites related to this measurement
123      * @since 9.3
124      */
125     List<ObservableSatellite> getSatellites();
126 
127     /** Estimate the theoretical value of the measurement.
128      * <p>
129      * The estimated value is the <em>combination</em> of the raw estimated
130      * value and all the modifiers that apply to the measurement.
131      * </p>
132      * @param iteration iteration number
133      * @param evaluation evaluations number
134      * @param states orbital states corresponding to {@link #getSatellites()} at measurement date
135      * @return estimated measurement
136      */
137     EstimatedMeasurement<T> estimate(int iteration, int evaluation, SpacecraftState[] states);
138 
139 }