1   /* Copyright 2002-2013 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 org.orekit.errors.OrekitException;
20  import org.orekit.propagation.SpacecraftState;
21  import org.orekit.propagation.events.EventDetector;
22  import org.orekit.propagation.semianalytical.dsst.utilities.AuxiliaryElements;
23  import org.orekit.time.AbsoluteDate;
24  
25  /** This interface represents a force modifying spacecraft motion for a {@link
26   *  org.orekit.propagation.semianalytical.dsst.DSSTPropagator DSSTPropagator}.
27   *  <p>
28   *  Objects implementing this interface are intended to be added to a {@link
29   *  org.orekit.propagation.semianalytical.dsst.DSSTPropagator DSST propagator}
30   *  before the propagation is started.
31   *  </p>
32   *  <p>
33   *  The propagator will call at the very beginning of a propagation the {@link
34   *  #initialize(AuxiliaryElements)} method allowing preliminary computation such
35   *  as truncation if needed.
36   *  </p>
37   *  <p>
38   *  Then the propagator will call at each step:
39   *  <ol>
40   *  <li>the {@link #initializeStep(AuxiliaryElements)} method.
41   *  The force model instance will extract all the elements needed before
42   *  computing the mean element rates.</li>
43   *  <li>the {@link #getMeanElementRate(SpacecraftState)} method.
44   *  The force model instance will extract all the state data needed to compute
45   *  the mean element rates that contribute to the mean state derivative.</li>
46   *  </ol>
47   *  </p>
48   *  <p>
49   *  The propagator will call the {@link #getShortPeriodicVariations(AbsoluteDate, double[])}
50   *  method at the end of the propagation in order to compute the short periodic
51   *  variations to be added to the mean elements to get the final state.
52   *  </p>
53   *
54   * @author Romain Di Constanzo
55   * @author Pascal Parraud
56   */
57  public interface DSSTForceModel {
58  
59      /** Performs initialization prior to propagation for the current force model.
60       *  <p>
61       *  This method aims at being called at the very beginning of a propagation.
62       *  </p>
63       *  @param aux auxiliary elements related to the current orbit
64       *  @throws OrekitException if some specific error occurs
65       */
66      void initialize(AuxiliaryElements aux)
67          throws OrekitException;
68  
69      /** Performs initialization at each integration step for the current force model.
70       *  <p>
71       *  This method aims at being called before mean elements rates computation.
72       *  </p>
73       *  @param aux auxiliary elements related to the current orbit
74       *  @throws OrekitException if some specific error occurs
75       */
76      void initializeStep(AuxiliaryElements aux)
77          throws OrekitException;
78  
79      /** Computes the mean equinoctial elements rates da<sub>i</sub> / dt.
80       *
81       *  @param state current state information: date, kinematics, attitude
82       *  @return the mean element rates dai/dt
83       *  @throws OrekitException if some specific error occurs
84       */
85      double[] getMeanElementRate(SpacecraftState state) throws OrekitException;
86  
87      /** Computes the short periodic variations.
88       *
89       *  @param date current date
90       *  @param meanElements mean elements at current date
91       *  @return the short periodic variations
92       *  @throws OrekitException if some specific error occurs
93       */
94      double[] getShortPeriodicVariations(AbsoluteDate date, double[] meanElements)
95          throws OrekitException;
96  
97      /** Get the discrete events related to the model.
98       * @return array of events detectors or null if the model is not
99       * related to any discrete events
100      */
101     EventDetector[] getEventsDetectors();
102 
103 }