1   /* Copyright 2002-2022 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  
23  /** Interface for extracting State Transition Matrices and Jacobians matrices from {@link SpacecraftState spacecraft state}.
24   * <p>
25   * The State Transition Matrix and Jacobians matrices with respect to propagation parameters are stored in the state
26   * as {@link SpacecraftState#getAdditionalState(String) additional states}. Each propagator and support classes has
27   * its own way to handle it. The interface leverages these differences which are implementation details and provides
28   * a higher level access to these matrices, regardless of haw they were computed and stored.
29   * </p>
30   * @author Luc Maisonobe
31   * @since 11.1
32   */
33  public interface MatricesHarvester {
34  
35      /** Set up reference state.
36       * <p>
37       * This method is called whenever the global propagation reference state changes.
38       * This corresponds to the start of propagation in batch least squares orbit determination
39       * or at prediction step for each measurement in Kalman filtering. Its goal is to allow
40       * the harvester to compute some internal data. Analytical models like TLE use it to
41       * compute analytical derivatives, semi-analytical models like DSST use it to compute
42       * short periodic terms, numerical models do not use it at all.
43       * </p>
44       * @param reference reference state to set
45       */
46      void setReferenceState(SpacecraftState reference);
47  
48      /** Extract state transition matrix from state.
49       * @param state spacecraft state
50       * @return state transition matrix, with semantics consistent with propagation,
51       * or null if no state transition matrix is available
52       * {@link org.orekit.orbits.OrbitType orbit type}.
53       */
54      RealMatrix getStateTransitionMatrix(SpacecraftState state);
55  
56      /** Get the Jacobian with respect to propagation parameters.
57       * @param state spacecraft state
58       * @return Jacobian with respect to propagation parameters, or null
59       * if there are no parameters
60       */
61      RealMatrix getParametersJacobian(SpacecraftState state);
62  
63      /** Get the names of the parameters in the matrix returned by {@link #getParametersJacobian}.
64       * <p>
65       * Beware that the names of the parameters are fully known only once all force models have
66       * been set up and their parameters properly selected. Applications that retrieve the matrices
67       * harvester first and select the force model parameters to retrieve afterwards (but obviously
68       * before starting propagation) must take care to wait until the parameters have been set up
69       * before they call this method. Calling the method too early would return wrong results.
70       * </p>
71       * <p>
72       * The names are returned in the Jacobians matrix columns order
73       * </p>
74       * @return names of the parameters (i.e. columns) of the Jacobian matrix
75       */
76      List<String> getJacobiansColumnsNames();
77  
78  }