1   /* Copyright 2010-2011 Centre National d'Études Spatiales
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.orekit.propagation.SpacecraftState;
20  import org.orekit.time.AbsoluteDate;
21  
22  /** This interface allows users to add their own differential equations to a numerical propagator.
23   *
24   * <p>
25   * In some cases users may need to integrate some problem-specific equations along with
26   * classical spacecraft equations of motions. One example is optimal control in low
27   * thrust where adjoint parameters linked to the minimized Hamiltonian must be integrated.
28   * Another example is formation flying or rendez-vous which use the Clohessy-Whiltshire
29   * equations for the relative motion.
30   * </p>
31   * <p>
32   * This interface allows users to add such equations to a {@link
33   * org.orekit.propagation.numerical.NumericalPropagator numerical propagator} or a {@link
34   * org.orekit.propagation.semianalytical.dsst.DSSTPropagator DSST propagator}. Users provide the
35   * equations as an implementation of this interface and register it to the propagator thanks to
36   * its {@link org.orekit.propagation.integration.AbstractIntegratedPropagator#addAdditionalEquations(AdditionalEquations)}
37   * method. Several such objects can be registered with each numerical propagator, but it is
38   * recommended to gather in the same object the sets of parameters which equations can interact
39   * on each others states.
40   * </p>
41   * <p>
42   * The additional parameters are gathered in a simple p array. The additional equations compute
43   * the pDot array, which is the time-derivative of the p array. Since the additional parameters
44   * p may also have an influence on the equations of motion themselves that should be accumulated
45   * to the main state derivatives (for example an equation linked to a complex thrust model may
46   * induce an acceleration and a mass change), the {@link #computeDerivatives(SpacecraftState, double[])
47   * computeDerivatives} method can return a double array that will be
48   * <em>added</em> to the main state derivatives. This means these equations can be used as an
49   * additional force model if needed. If the additional parameters have no influence at all on
50   * the main spacecraft state, a null reference may be returned.
51   * </p>
52   * <p>
53   * This interface is the numerical (read not already integrated) counterpart of
54   * the {@link org.orekit.propagation.AdditionalStateProvider} interface.
55   * It allows to append various additional state parameters to any {@link
56   * org.orekit.propagation.numerical.NumericalPropagator numerical propagator} or {@link
57   * org.orekit.propagation.semianalytical.dsst.DSSTPropagator DSST propagator}.
58   * </p>
59   * @see AbstractIntegratedPropagator
60   * @see org.orekit.propagation.AdditionalStateProvider
61   * @author Luc Maisonobe
62   * @deprecated as of 11.1, replaced by {@link AdditionalDerivativesProvider}
63   */
64  @Deprecated
65  public interface AdditionalEquations {
66  
67      /** Get the name of the additional state.
68       * @return name of the additional state
69       */
70      String getName();
71  
72      /**
73       * Initialize the equations at the start of propagation.
74       *
75       * <p>
76       * This method will be called once at propagation start,
77       * before any calls to {@link #computeDerivatives(SpacecraftState, double[])}.
78       * </p>
79       *
80       * <p>
81       * The default implementation of this method does nothing.
82       * </p>
83       *
84       * @param initialState initial state information at the start of propagation.
85       * @param target       date of propagation. Not equal to {@code
86       *                     initialState.getDate()}.
87       */
88      default void init(final SpacecraftState initialState, final AbsoluteDate target) {
89          // nothing by default
90      }
91  
92      /** Compute the derivatives related to the additional state parameters.
93       * <p>
94       * When this method is called, the spacecraft state contains the main
95       * state (orbit, attitude and mass), all the states provided through
96       * the {@link org.orekit.propagation.AdditionalStateProvider additional
97       * state providers} registered to the propagator, and the additional state
98       * integrated using this equation. It does <em>not</em> contains any other
99       * states to be integrated alongside during the same propagation.
100      * </p>
101      * @param s current state information: date, kinematics, attitude, and
102      * additional state
103      * @param pDot placeholder where the derivatives of the additional parameters
104      * should be put
105      * @return cumulative effect of the equations on the main state (may be null if
106      * equations do not change main state at all)
107      */
108     double[] computeDerivatives(SpacecraftState s,  double[] pDot);
109 
110 }