1   /* Copyright 2002-2017 CS Systèmes d'Information
2    * Licensed to CS Systèmes d'Information (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.semianalytical.dsst.forces;
18  
19  import java.util.List;
20  
21  import org.orekit.attitudes.AttitudeProvider;
22  import org.orekit.errors.OrekitException;
23  import org.orekit.propagation.SpacecraftState;
24  import org.orekit.propagation.events.EventDetector;
25  import org.orekit.propagation.semianalytical.dsst.utilities.AuxiliaryElements;
26  
27  /** This interface represents a force modifying spacecraft motion for a {@link
28   *  org.orekit.propagation.semianalytical.dsst.DSSTPropagator DSSTPropagator}.
29   *  <p>
30   *  Objects implementing this interface are intended to be added to a {@link
31   *  org.orekit.propagation.semianalytical.dsst.DSSTPropagator DSST propagator}
32   *  before the propagation is started.
33   *  </p>
34   *  <p>
35   *  The propagator will call at the very beginning of a propagation the {@link
36   *  #initialize(AuxiliaryElements, boolean)} method allowing preliminary computation
37   *  such as truncation if needed.
38   *  </p>
39   *  <p>
40   *  Then the propagator will call at each step:
41   *  <ol>
42   *  <li>the {@link #initializeStep(AuxiliaryElements)} method.
43   *  The force model instance will extract all the elements needed before
44   *  computing the mean element rates.</li>
45   *  <li>the {@link #getMeanElementRate(SpacecraftState)} method.
46   *  The force model instance will extract all the state data needed to compute
47   *  the mean element rates that contribute to the mean state derivative.</li>
48   *  <li>the {@link #updateShortPeriodTerms(SpacecraftState...)} method,
49   *  if osculating parameters are desired, on a sample of points within the
50   *  last step.</li>
51   *  </ol>
52   *
53   * @author Romain Di Constanzo
54   * @author Pascal Parraud
55   */
56  public interface DSSTForceModel {
57  
58      /** Performs initialization prior to propagation for the current force model.
59       *  <p>
60       *  This method aims at being called at the very beginning of a propagation.
61       *  </p>
62       *  @param aux auxiliary elements related to the current orbit
63       *  @param meanOnly only mean elements are used during the propagation
64       *  @return a list of objects that will hold short period terms (the objects
65       *  are also retained by the force model, which will update them during propagation)
66       *  @throws OrekitException if some specific error occurs
67       */
68      List<ShortPeriodTerms> initialize(AuxiliaryElements aux, boolean meanOnly)
69          throws OrekitException;
70  
71      /** Performs initialization at each integration step for the current force model.
72       *  <p>
73       *  This method aims at being called before mean elements rates computation.
74       *  </p>
75       *  @param aux auxiliary elements related to the current orbit
76       *  @throws OrekitException if some specific error occurs
77       */
78      void initializeStep(AuxiliaryElements aux)
79          throws OrekitException;
80  
81      /** Computes the mean equinoctial elements rates da<sub>i</sub> / dt.
82       *
83       *  @param state current state information: date, kinematics, attitude
84       *  @return the mean element rates dai/dt
85       *  @throws OrekitException if some specific error occurs
86       */
87      double[] getMeanElementRate(SpacecraftState state) throws OrekitException;
88  
89      /** Get the discrete events related to the model.
90       * @return array of events detectors or null if the model is not
91       * related to any discrete events
92       */
93      EventDetector[] getEventsDetectors();
94  
95      /** Register an attitude provider.
96       * <p>
97       * Register an attitude provider that can be used by the force model.
98       * </p>
99       * @param provider the {@link AttitudeProvider}
100      */
101     void registerAttitudeProvider(AttitudeProvider provider);
102 
103     /** Update the short period terms.
104      * <p>
105      * The {@link ShortPeriodTerms short period terms} that will be updated
106      * are the ones that were returned during the call to {@link
107      * #initialize(AuxiliaryElements, boolean)}.
108      * </p>
109      * @param meanStates mean states information: date, kinematics, attitude
110      * @throws OrekitException if some specific error occurs
111      */
112     void updateShortPeriodTerms(SpacecraftState... meanStates)
113         throws OrekitException;
114 
115 }