AbstractMatricesHarvester.java

  1. /* Copyright 2002-2024 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. import java.util.List;

  19. import org.hipparchus.linear.MatrixUtils;
  20. import org.hipparchus.linear.RealMatrix;
  21. import org.orekit.orbits.PositionAngleType;
  22. import org.orekit.utils.DoubleArrayDictionary;

  23. /** Base harvester between two-dimensional Jacobian matrices and one-dimensional {@link
  24.  * SpacecraftState#getAdditionalState(String) additional state arrays}.
  25.  * @author Luc Maisonobe
  26.  * @since 11.1
  27.  */
  28. public abstract class AbstractMatricesHarvester implements MatricesHarvester {

  29.     /** State dimension, fixed to 6. */
  30.     public static final int STATE_DIMENSION = 6;

  31.     /** Identity conversion matrix. */
  32.     private static final double[][] IDENTITY = {
  33.         { 1.0, 0.0, 0.0, 0.0, 0.0, 0.0 },
  34.         { 0.0, 1.0, 0.0, 0.0, 0.0, 0.0 },
  35.         { 0.0, 0.0, 1.0, 0.0, 0.0, 0.0 },
  36.         { 0.0, 0.0, 0.0, 1.0, 0.0, 0.0 },
  37.         { 0.0, 0.0, 0.0, 0.0, 1.0, 0.0 },
  38.         { 0.0, 0.0, 0.0, 0.0, 0.0, 1.0 }
  39.     };

  40.     /** Initial State Transition Matrix. */
  41.     private final RealMatrix initialStm;

  42.     /** Initial columns of the Jacobians matrix with respect to parameters. */
  43.     private final DoubleArrayDictionary initialJacobianColumns;

  44.     /** State Transition Matrix state name. */
  45.     private final String stmName;

  46.     /** Simple constructor.
  47.      * <p>
  48.      * The arguments for initial matrices <em>must</em> be compatible with the {@link org.orekit.orbits.OrbitType orbit type}
  49.      * and {@link PositionAngleType position angle} that will be used by propagator
  50.      * </p>
  51.      * @param stmName State Transition Matrix state name
  52.      * @param initialStm initial State Transition Matrix ∂Y/∂Y₀,
  53.      * if null (which is the most frequent case), assumed to be 6x6 identity
  54.      * @param initialJacobianColumns initial columns of the Jacobians matrix with respect to parameters,
  55.      * if null or if some selected parameters are missing from the dictionary, the corresponding
  56.      * initial column is assumed to be 0
  57.      */
  58.     protected AbstractMatricesHarvester(final String stmName, final RealMatrix initialStm, final DoubleArrayDictionary initialJacobianColumns) {
  59.         this.stmName                = stmName;
  60.         this.initialStm             = initialStm == null ? MatrixUtils.createRealIdentityMatrix(STATE_DIMENSION) : initialStm;
  61.         this.initialJacobianColumns = initialJacobianColumns == null ? new DoubleArrayDictionary() : initialJacobianColumns;
  62.     }

  63.     /** Get the State Transition Matrix state name.
  64.      * @return State Transition Matrix state name
  65.      */
  66.     public String getStmName() {
  67.         return stmName;
  68.     }

  69.     /** Get the initial State Transition Matrix.
  70.      * @return initial State Transition Matrix
  71.      */
  72.     public RealMatrix getInitialStateTransitionMatrix() {
  73.         return initialStm;
  74.     }

  75.     /** Get the initial column of Jacobian matrix with respect to named parameter.
  76.      * @param columnName name of the column
  77.      * @return initial column of the Jacobian matrix
  78.      */
  79.     public double[] getInitialJacobianColumn(final String columnName) {
  80.         final DoubleArrayDictionary.Entry entry = initialJacobianColumns.getEntry(columnName);
  81.         return entry == null ? new double[STATE_DIMENSION] : entry.getValue();
  82.     }

  83.     /** Get the conversion Jacobian between state parameters and parameters used for derivatives.
  84.      * <p>
  85.      * The base implementation returns identity, which is suitable for DSST and TLE propagators,
  86.      * as state parameters and parameters used for derivatives are the same.
  87.      * </p>
  88.      * <p>
  89.      * For Numerical propagator, parameters used for derivatives are Cartesian
  90.      * and they can be different from state parameters because the numerical propagator can accept different type
  91.      * of orbits, so the method is overridden in derived classes.
  92.      * </p>
  93.      * @param state spacecraft state
  94.      * @return conversion Jacobian
  95.      */
  96.     protected double[][] getConversionJacobian(final SpacecraftState state) {
  97.         return IDENTITY;
  98.     }

  99.     /** {@inheritDoc} */
  100.     @Override
  101.     public void setReferenceState(final SpacecraftState reference) {
  102.         // nothing to do
  103.     }

  104.     /** {@inheritDoc} */
  105.     @Override
  106.     public RealMatrix getStateTransitionMatrix(final SpacecraftState state) {

  107.         if (!state.hasAdditionalState(stmName)) {
  108.             return null;
  109.         }

  110.         // get the conversion Jacobian
  111.         final double[][] dYdC = getConversionJacobian(state);

  112.         // extract the additional state
  113.         final double[] p = state.getAdditionalState(stmName);

  114.         // compute dYdY0 = dYdC * dCdY0
  115.         final RealMatrix  dYdY0 = MatrixUtils.createRealMatrix(STATE_DIMENSION, STATE_DIMENSION);
  116.         for (int i = 0; i < STATE_DIMENSION; i++) {
  117.             final double[] rowC = dYdC[i];
  118.             for (int j = 0; j < STATE_DIMENSION; ++j) {
  119.                 double sum = 0;
  120.                 int pIndex = j;
  121.                 for (int k = 0; k < STATE_DIMENSION; ++k) {
  122.                     sum += rowC[k] * p[pIndex];
  123.                     pIndex += STATE_DIMENSION;
  124.                 }
  125.                 dYdY0.setEntry(i, j, sum);
  126.             }
  127.         }

  128.         return dYdY0;

  129.     }

  130.     /** {@inheritDoc} */
  131.     @Override
  132.     public RealMatrix getParametersJacobian(final SpacecraftState state) {

  133.         final List<String> columnsNames = getJacobiansColumnsNames();

  134.         if (columnsNames == null || columnsNames.isEmpty()) {
  135.             return null;
  136.         }

  137.         // get the conversion Jacobian
  138.         final double[][] dYdC = getConversionJacobian(state);

  139.         // compute dYdP = dYdC * dCdP
  140.         final RealMatrix dYdP = MatrixUtils.createRealMatrix(STATE_DIMENSION, columnsNames.size());
  141.         for (int j = 0; j < columnsNames.size(); j++) {
  142.             final double[] p = state.getAdditionalState(columnsNames.get(j));
  143.             for (int i = 0; i < STATE_DIMENSION; ++i) {
  144.                 final double[] dYdCi = dYdC[i];
  145.                 double sum = 0;
  146.                 for (int k = 0; k < STATE_DIMENSION; ++k) {
  147.                     sum += dYdCi[k] * p[k];
  148.                 }
  149.                 dYdP.setEntry(i, j, sum);
  150.             }
  151.         }

  152.         return dYdP;

  153.     }

  154.     /** Freeze the names of the Jacobian columns.
  155.      * <p>
  156.      * This method is called when propagation starts, i.e. when configuration is completed
  157.      * </p>
  158.      */
  159.     public abstract void freezeColumnsNames();

  160. }