1   /* Copyright 2002-2026 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.propagation;
18  
19  import java.util.List;
20  
21  import org.hipparchus.linear.RealMatrix;
22  import org.orekit.orbits.OrbitType;
23  import org.orekit.orbits.PositionAngleType;
24  
25  /** Interface for extracting State Transition Matrices and Jacobians matrices from {@link SpacecraftState spacecraft state}.
26   * <p>
27   * The State Transition Matrix and Jacobians matrices with respect to propagation parameters are stored in the state
28   * as {@link SpacecraftState#getAdditionalState(String) additional states}. Each propagator and support classes have
29   * their own way to handle them. The interface leverages these differences which are implementation details and provides
30   * a higher level access to these matrices, regardless of how they were computed and stored.
31   * </p>
32   * <img src="doc-files/harvesters-class-diagram.png" alt="class diagram">
33   * @author Luc Maisonobe
34   * @since 11.1
35   */
36  public interface MatricesHarvester {
37  
38      /** Set up reference state.
39       * <p>
40       * This method is called whenever the global propagation reference state changes.
41       * This corresponds to the start of propagation in batch least squares orbit determination
42       * or at prediction step for each measurement in Kalman filtering. Its goal is to allow
43       * the harvester to compute some internal data. Analytical models like TLE use it to
44       * compute analytical derivatives, semi-analytical models like DSST use it to compute
45       * short periodic terms, numerical models do not use it at all.
46       * </p>
47       * @param reference reference state to set
48       */
49      void setReferenceState(SpacecraftState reference);
50  
51      /** Extract state transition matrix from state.
52       * <p>
53       * Some propagators use an orbit type B as the propagator builder parameter, and
54       * a different type Y for the propagated orbit. Typical examples are TLE or specialized
55       * GNSS propagators that use Keplerian-like builder parameters but produce Cartesian states.
56       * This method is <em>not</em> aware of such parameters change, so it always computes dY/dY₀
57       * with the same representation for the current propagated state Y and the initial state Y₀.
58       * </p>
59       * <p>
60       * In order to compute dY/dB₀ where the current propagated state Y and the initial
61       * building state B₀ have different types, one should compute dY/dB₀ = dY/dY₀ dY₀/dB₀,
62       * where the first factor dY/dY₀ is given by this method and the second factor dY₀/dB₀ is
63       * given by the method {@link #getStateJacobianVsBuilderParameters(SpacecraftState)}.
64       * </p>
65       * @param state spacecraft state
66       * @return state transition matrix, with semantics consistent with propagation,
67       * or null if no state transition matrix is available
68       * {@link org.orekit.orbits.OrbitType orbit type}.
69       */
70      RealMatrix getStateTransitionMatrix(SpacecraftState state);
71  
72      /** Get transformation Jacobian between builder parameters and propagated state.
73       * <p>
74       * Some propagators use an orbit type B as the propagator builder parameter, and
75       * a different type Y for the propagated orbit. Typical examples are TLE or specialized
76       * GNSS propagators that use Keplerian-like builder parameters but produce Cartesian states.
77       * This method allows to convert between these types.
78       * </p>
79       * <p>
80       * Applying this method to the propagator initial state gives the Jacobian dY₀/dB₀ between the initial propagated
81       * state and the initial builder parameters.
82       * </p>
83       * @param state state at which the Jacobian should be evaluated
84       * @return jacobian matrix dY/dB where Y is the propagated state, using the representation
85       * given by {@link #getOrbitType()} and {@link #getPositionAngleType()}, and B is the set of
86       * propagator builder parameters representing this very same state, or null if Y and B have
87       * the same type, in which case callers must consider the Jacobian is the identity matrix
88       * @since 14.0
89       */
90      default RealMatrix getStateJacobianVsBuilderParameters(final SpacecraftState state) {
91          return null;
92      }
93  
94      /** Get the Jacobian with respect to propagation parameters.
95       * @param state spacecraft state
96       * @return Jacobian with respect to propagation parameters, or null
97       * if there are no parameters
98       */
99      RealMatrix getParametersJacobian(SpacecraftState state);
100 
101     /** Get the names of the parameters in the matrix returned by {@link #getParametersJacobian}.
102      * <p>
103      * Beware that the names of the parameters are fully known only once all force models have
104      * been set up and their parameters properly selected. Applications that retrieve the matrices
105      * harvester first and select the force model parameters to retrieve afterwards (but obviously
106      * before starting propagation) must take care to wait until the parameters have been set up
107      * before they call this method. Calling the method too early would return wrong results.
108      * </p>
109      * <p>
110      * The names are returned in the Jacobians matrix columns order
111      * </p>
112      * @return names of the parameters (i.e. columns) of the Jacobian matrix
113      */
114     List<String> getJacobiansColumnsNames();
115 
116     /**
117      * Get the orbit type used for the matrix computation.
118      * @return the orbit type used for the matrix computation
119      */
120     OrbitType getOrbitType();
121 
122     /**
123      * Get the position angle used for the matrix computation.
124      * <p>
125      * Irrelevant if {@link #getOrbitType()} returns {@link OrbitType#CARTESIAN}.
126      * </p>
127      * @return the position angle used for the matrix computation
128      */
129     PositionAngleType getPositionAngleType();
130 
131 }