1   /* Copyright 2002-2015 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.forces;
18  
19  import org.apache.commons.math3.analysis.differentiation.DerivativeStructure;
20  import org.apache.commons.math3.geometry.euclidean.threed.FieldRotation;
21  import org.apache.commons.math3.geometry.euclidean.threed.FieldVector3D;
22  import org.apache.commons.math3.ode.ParameterizedODE;
23  import org.orekit.errors.OrekitException;
24  import org.orekit.frames.Frame;
25  import org.orekit.propagation.SpacecraftState;
26  import org.orekit.propagation.events.EventDetector;
27  import org.orekit.propagation.numerical.TimeDerivativesEquations;
28  import org.orekit.time.AbsoluteDate;
29  
30  /** This interface represents a force modifying spacecraft motion.
31   *
32   * <p>
33   * Objects implementing this interface are intended to be added to a
34   * {@link org.orekit.propagation.numerical.NumericalPropagator numerical propagator}
35   * before the propagation is started.
36   * <p>
37   * <p>
38   * The propagator will call at each step the {@link #addContribution(SpacecraftState,
39   * TimeDerivativesEquations)} method. The force model instance will extract all the
40   * state data it needs (date,position, velocity, frame, attitude, mass) from the first
41   * parameter. From these state data, it will compute the perturbing acceleration. It
42   * will then add this acceleration to the second parameter which will take thins
43   * contribution into account and will use the Gauss equations to evaluate its impact
44   * on the global state derivative.
45   * </p>
46   * <p>
47   * Force models which create discontinuous acceleration patterns (typically for maneuvers
48   * start/stop or solar eclipses entry/exit) must provide one or more {@link
49   * org.orekit.propagation.events.EventDetector events detectors} to the
50   * propagator thanks to their {@link #getEventsDetectors()} method. This method
51   * is called once just before propagation starts. The events states will be checked by
52   * the propagator to ensure accurate propagation and proper events handling.
53   * </p>
54   *
55   * @author Mathieu Rom&eacute;ro
56   * @author Luc Maisonobe
57   * @author V&eacute;ronique Pommier-Maurussane
58   */
59  public interface ForceModel extends ParameterizedODE {
60  
61      /** Compute the contribution of the force model to the perturbing
62       * acceleration.
63       * @param s current state information: date, kinematics, attitude
64       * @param adder object where the contribution should be added
65       * @exception OrekitException if some specific error occurs
66       */
67      void addContribution(SpacecraftState s, TimeDerivativesEquations adder)
68          throws OrekitException;
69  
70      /** Compute acceleration derivatives with respect to state parameters.
71       * <p>
72       * The derivatives should be computed with respect to position, velocity
73       * and optionnaly mass. The input parameters already take into account the
74       * free parameters (6 or 7 depending on derivation with respect to mass
75       * being considered or not) and order (always 1). Free parameters at indices
76       * 0, 1 and 2 correspond to derivatives with respect to position. Free
77       * parameters at indices 3, 4 and 5 correspond to derivatives with respect
78       * to velocity. Free parameter at index 6 (if present) corresponds to
79       * to derivatives with respect to mass.
80       * </p>
81       * @param date current date
82       * @param frame inertial reference frame for state (both orbit and attitude)
83       * @param position position of spacecraft in reference frame
84       * @param velocity velocity of spacecraft in reference frame
85       * @param rotation orientation (attitude) of the spacecraft with respect to reference frame
86       * @param mass spacecraft mass
87       * @return acceleration with all derivatives specified by the input parameters own derivatives
88       * @exception OrekitException if derivatives cannot be computed
89       * @since 6.0
90       */
91      FieldVector3D<DerivativeStructure> accelerationDerivatives(AbsoluteDate date, Frame frame,
92                                         FieldVector3D<DerivativeStructure> position, FieldVector3D<DerivativeStructure> velocity,
93                                         FieldRotation<DerivativeStructure> rotation, DerivativeStructure mass)
94          throws OrekitException;
95  
96      /** Compute acceleration derivatives with respect to additional parameters.
97       * @param s spacecraft state
98       * @param paramName name of the parameter with respect to which derivatives are required
99       * @return acceleration with all derivatives specified by the input parameters own derivatives
100      * @exception OrekitException if derivatives cannot be computed
101      * @since 6.0
102      */
103     FieldVector3D<DerivativeStructure> accelerationDerivatives(SpacecraftState s, String paramName)
104         throws OrekitException;
105 
106     /** Get the discrete events related to the model.
107      * @return array of events detectors or null if the model is not
108      * related to any discrete events
109      */
110     EventDetector[] getEventsDetectors();
111 
112 }