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.integration; 18 19 import org.hipparchus.CalculusFieldElement; 20 import org.orekit.propagation.FieldAdditionalDataProvider; 21 import org.orekit.propagation.FieldSpacecraftState; 22 import org.orekit.time.FieldAbsoluteDate; 23 24 /** Provider for additional derivatives. 25 * 26 * <p> 27 * In some cases users may need to integrate some problem-specific equations along with 28 * classical spacecraft equations of motions. One example is optimal control in low 29 * thrust where adjoint parameters linked to the minimized Hamiltonian must be integrated. 30 * Another example is formation flying or rendez-vous which use the Clohessy-Whiltshire 31 * equations for the relative motion. 32 * </p> 33 * <p> 34 * This interface allows users to add such equations to a {@link 35 * org.orekit.propagation.numerical.FieldNumericalPropagator numerical propagator} or a {@link 36 * org.orekit.propagation.semianalytical.dsst.FieldDSSTPropagator DSST propagator}. Users provide the 37 * equations as an implementation of this interface and register it to the propagator thanks to 38 * its {@link FieldAbstractIntegratedPropagator#addAdditionalDerivativesProvider(FieldAdditionalDerivativesProvider)} 39 * method. Several such objects can be registered with each numerical propagator, but it is 40 * recommended to gather in the same object the sets of parameters which equations can interact 41 * on each others states. 42 * </p> 43 * <p> 44 * This interface is the numerical (read not already integrated) counterpart of 45 * the {@link FieldAdditionalDataProvider} interface. 46 * It allows to append various additional state parameters to any {@link 47 * org.orekit.propagation.numerical.FieldNumericalPropagator numerical propagator} or {@link 48 * org.orekit.propagation.semianalytical.dsst.FieldDSSTPropagator DSST propagator}. 49 * </p> 50 * @see org.orekit.propagation.integration.FieldAbstractIntegratedPropagator 51 * @author Luc Maisonobe 52 * @since 11.1 53 * @param <T> type of the field elements 54 */ 55 public interface FieldAdditionalDerivativesProvider<T extends CalculusFieldElement<T>> { 56 57 /** Get the name of the additional derivatives (which will become state once integrated). 58 * @return name of the additional state (names containing "orekit" 59 * with any case are reserved for the library internal use) 60 */ 61 String getName(); 62 63 /** Get the dimension of the generated derivative. 64 * @return dimension of the generated 65 */ 66 int getDimension(); 67 68 /** Initialize the generator at the start of propagation. 69 * @param initialState initial state information at the start of propagation 70 * @param target date of propagation 71 */ 72 default void init(final FieldSpacecraftState<T> initialState, final FieldAbsoluteDate<T> target) { 73 // nothing by default 74 } 75 76 /** Check if this provider should yield so another provider has an opportunity to add missing parts. 77 * <p> 78 * Decision to yield is often based on an additional state being {@link FieldSpacecraftState#hasAdditionalData(String) 79 * already available} in the provided {@code state} (but it could theoretically also depend on 80 * an additional state derivative being {@link FieldSpacecraftState#hasAdditionalStateDerivative(String) 81 * already available}, or any other criterion). If for example a provider needs the state transition 82 * matrix, it could implement this method as: 83 * </p> 84 * <pre>{@code 85 * public boolean yields(final FieldSpacecraftState<T> state) { 86 * return !state.getAdditionalStates().containsKey("STM"); 87 * } 88 * }</pre> 89 * <p> 90 * The default implementation returns {@code false}, meaning that derivative data can be 91 * {@link #combinedDerivatives(FieldSpacecraftState) computed} immediately. 92 * </p> 93 * @param state state to handle 94 * @return true if this provider should yield so another provider has an opportunity to add missing parts 95 * as the state is incrementally built up 96 */ 97 default boolean yields(FieldSpacecraftState<T> state) { 98 return false; 99 } 100 101 /** Compute the derivatives related to the additional state (and optionally main state increments). 102 * @param s current state information: date, kinematics, attitude, and 103 * additional states this equations depend on (according to the 104 * {@link #yields(FieldSpacecraftState) yields} method) 105 * @return computed combined derivatives, which may include some incremental 106 * coupling effect to add to main state derivatives 107 * @since 11.2 108 */ 109 FieldCombinedDerivatives<T> combinedDerivatives(FieldSpacecraftState<T> s); 110 111 }