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.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   * @author Luc Maisonobe
33   * @since 11.1
34   */
35  public interface MatricesHarvester {
36  
37      /** Set up reference state.
38       * <p>
39       * This method is called whenever the global propagation reference state changes.
40       * This corresponds to the start of propagation in batch least squares orbit determination
41       * or at prediction step for each measurement in Kalman filtering. Its goal is to allow
42       * the harvester to compute some internal data. Analytical models like TLE use it to
43       * compute analytical derivatives, semi-analytical models like DSST use it to compute
44       * short periodic terms, numerical models do not use it at all.
45       * </p>
46       * @param reference reference state to set
47       */
48      void setReferenceState(SpacecraftState reference);
49  
50      /** Extract state transition matrix from state.
51       * @param state spacecraft state
52       * @return state transition matrix, with semantics consistent with propagation,
53       * or null if no state transition matrix is available
54       * {@link org.orekit.orbits.OrbitType orbit type}.
55       */
56      RealMatrix getStateTransitionMatrix(SpacecraftState state);
57  
58      /** Get the Jacobian with respect to propagation parameters.
59       * @param state spacecraft state
60       * @return Jacobian with respect to propagation parameters, or null
61       * if there are no parameters
62       */
63      RealMatrix getParametersJacobian(SpacecraftState state);
64  
65      /** Get the names of the parameters in the matrix returned by {@link #getParametersJacobian}.
66       * <p>
67       * Beware that the names of the parameters are fully known only once all force models have
68       * been set up and their parameters properly selected. Applications that retrieve the matrices
69       * harvester first and select the force model parameters to retrieve afterwards (but obviously
70       * before starting propagation) must take care to wait until the parameters have been set up
71       * before they call this method. Calling the method too early would return wrong results.
72       * </p>
73       * <p>
74       * The names are returned in the Jacobians matrix columns order
75       * </p>
76       * @return names of the parameters (i.e. columns) of the Jacobian matrix
77       */
78      List<String> getJacobiansColumnsNames();
79  
80      /**
81       * Get the orbit type used for the matrix computation.
82       * @return the orbit type used for the matrix computation
83       */
84      OrbitType getOrbitType();
85  
86      /**
87       * Get the position angle used for the matrix computation.
88       * <p>
89       * Irrelevant if {@link #getOrbitType()} returns {@link OrbitType#CARTESIAN}.
90       * </p>
91       * @return the position angle used for the matrix computation
92       */
93      PositionAngleType getPositionAngleType();
94  
95  }