ForceModel.java

  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.forces;

  18. import java.util.stream.Stream;

  19. import org.hipparchus.Field;
  20. import org.hipparchus.RealFieldElement;
  21. import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
  22. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  23. import org.hipparchus.util.MathArrays;
  24. import org.orekit.errors.OrekitException;
  25. import org.orekit.propagation.FieldSpacecraftState;
  26. import org.orekit.propagation.SpacecraftState;
  27. import org.orekit.propagation.events.EventDetector;
  28. import org.orekit.propagation.events.FieldEventDetector;
  29. import org.orekit.propagation.numerical.FieldTimeDerivativesEquations;
  30. import org.orekit.propagation.numerical.TimeDerivativesEquations;
  31. import org.orekit.time.AbsoluteDate;
  32. import org.orekit.utils.ParameterDriver;

  33. /** This interface represents a force modifying spacecraft motion.
  34.  *
  35.  * <p>
  36.  * Objects implementing this interface are intended to be added to a
  37.  * {@link org.orekit.propagation.numerical.NumericalPropagator numerical propagator}
  38.  * before the propagation is started.
  39.  *
  40.  * <p>
  41.  * The propagator will call at each step the {@link #addContribution(SpacecraftState,
  42.  * TimeDerivativesEquations)} method. The force model instance will extract all the
  43.  * state data it needs (date, position, velocity, frame, attitude, mass) from the first
  44.  * parameter. From these state data, it will compute the perturbing acceleration. It
  45.  * will then add this acceleration to the second parameter which will take thins
  46.  * contribution into account and will use the Gauss equations to evaluate its impact
  47.  * on the global state derivative.
  48.  * </p>
  49.  * <p>
  50.  * Force models which create discontinuous acceleration patterns (typically for maneuvers
  51.  * start/stop or solar eclipses entry/exit) must provide one or more {@link
  52.  * org.orekit.propagation.events.EventDetector events detectors} to the
  53.  * propagator thanks to their {@link #getEventsDetectors()} method. This method
  54.  * is called once just before propagation starts. The events states will be checked by
  55.  * the propagator to ensure accurate propagation and proper events handling.
  56.  * </p>
  57.  *
  58.  * @author Mathieu Rom&eacute;ro
  59.  * @author Luc Maisonobe
  60.  * @author V&eacute;ronique Pommier-Maurussane
  61.  */
  62. public interface ForceModel {

  63.     /**
  64.      * Initialize the force model at the start of propagation. This method will be called
  65.      * before any calls to {@link #addContribution(SpacecraftState, TimeDerivativesEquations)},
  66.      * {@link #addContribution(FieldSpacecraftState, FieldTimeDerivativesEquations)},
  67.      * {@link #acceleration(SpacecraftState, double[])} or {@link #acceleration(FieldSpacecraftState, RealFieldElement[])}
  68.      *
  69.      * <p> The default implementation of this method does nothing.</p>
  70.      *
  71.      * @param initialState spacecraft state at the start of propagation.
  72.      * @param target       date of propagation. Not equal to {@code initialState.getDate()}.
  73.      * @throws OrekitException if an implementing class overrides the default behavior and
  74.      *                         takes some action that throws an {@link OrekitException}.
  75.      */
  76.     default void init(SpacecraftState initialState, AbsoluteDate target)
  77.         throws OrekitException {
  78.     }

  79.     /** Compute the contribution of the force model to the perturbing
  80.      * acceleration.
  81.      * <p>
  82.      * The default implementation simply adds the {@link #acceleration(SpacecraftState, double[]) acceleration}
  83.      * as a non-Keplerian acceleration.
  84.      * </p>
  85.      * @param s current state information: date, kinematics, attitude
  86.      * @param adder object where the contribution should be added
  87.      * @exception OrekitException if some specific error occurs
  88.      */
  89.     default void addContribution(SpacecraftState s, TimeDerivativesEquations adder)
  90.         throws OrekitException {
  91.         adder.addNonKeplerianAcceleration(acceleration(s, getParameters()));
  92.     }

  93.     /** Compute the contribution of the force model to the perturbing
  94.      * acceleration.
  95.      * @param s current state information: date, kinematics, attitude
  96.      * @param adder object where the contribution should be added
  97.      * @param <T> type of the elements
  98.      * @exception OrekitException if some specific error occurs
  99.      */
  100.     default <T extends RealFieldElement<T>> void addContribution(FieldSpacecraftState<T> s, FieldTimeDerivativesEquations<T> adder)
  101.         throws OrekitException {
  102.         adder.addNonKeplerianAcceleration(acceleration(s, getParameters(s.getDate().getField())));
  103.     }

  104.     /** Get force model parameters.
  105.      * @return force model parameters
  106.      * @since 9.0
  107.      */
  108.     default double[] getParameters() {
  109.         final ParameterDriver[] drivers = getParametersDrivers();
  110.         final double[] parameters = new double[drivers.length];
  111.         for (int i = 0; i < drivers.length; ++i) {
  112.             parameters[i] = drivers[i].getValue();
  113.         }
  114.         return parameters;
  115.     }

  116.     /** Get force model parameters.
  117.      * @param field field to which the elements belong
  118.      * @param <T> type of the elements
  119.      * @return force model parameters
  120.      * @since 9.0
  121.      */
  122.     default <T extends RealFieldElement<T>> T[] getParameters(final Field<T> field) {
  123.         final ParameterDriver[] drivers = getParametersDrivers();
  124.         final T[] parameters = MathArrays.buildArray(field, drivers.length);
  125.         for (int i = 0; i < drivers.length; ++i) {
  126.             parameters[i] = field.getZero().add(drivers[i].getValue());
  127.         }
  128.         return parameters;
  129.     }

  130.     /** Check if force models depends on position only.
  131.      * @return true if force model depends on position only, false
  132.      * if it depends on velocity, either directly or due to a dependency
  133.      * on attitude
  134.      * @since 9.0
  135.      */
  136.     boolean dependsOnPositionOnly();

  137.     /** Compute acceleration.
  138.      * @param s current state information: date, kinematics, attitude
  139.      * @param parameters values of the force model parameters
  140.      * @return acceleration in same frame as state
  141.      * @exception OrekitException if some specific error occurs
  142.      * @since 9.0
  143.      */
  144.     Vector3D acceleration(SpacecraftState s, double[] parameters)
  145.         throws OrekitException;

  146.     /** Compute acceleration.
  147.      * @param s current state information: date, kinematics, attitude
  148.      * @param parameters values of the force model parameters
  149.      * @return acceleration in same frame as state
  150.      * @param <T> type of the elements
  151.      * @exception OrekitException if some specific error occurs
  152.      * @since 9.0
  153.      */
  154.     <T extends RealFieldElement<T>> FieldVector3D<T> acceleration(FieldSpacecraftState<T> s, T[] parameters)
  155.         throws OrekitException;

  156.     /** Get the discrete events related to the model.
  157.      * @return stream of events detectors
  158.      */
  159.     Stream<EventDetector> getEventsDetectors();

  160.     /** Get the discrete events related to the model.
  161.      * @param field field to which the state belongs
  162.      * @param <T> extends RealFieldElement<T>
  163.      * @return stream of events detectors
  164.      */
  165.     <T extends RealFieldElement<T>> Stream<FieldEventDetector<T>> getFieldEventsDetectors(Field<T> field);

  166.     /** Get the drivers for force model parameters.
  167.      * @return drivers for force model parameters
  168.      * @since 8.0
  169.      */
  170.     ParameterDriver[] getParametersDrivers();

  171.     /** Get parameter value from its name.
  172.      * @param name parameter name
  173.      * @return parameter value
  174.      * @exception OrekitException if parameter is not supported
  175.      * @since 8.0
  176.      */
  177.     ParameterDriver getParameterDriver(String name) throws OrekitException;

  178.     /** Check if a parameter is supported.
  179.      * <p>Supported parameters are those listed by {@link #getParametersDrivers()}.</p>
  180.      * @param name parameter name to check
  181.      * @return true if the parameter is supported
  182.      * @see #getParametersDrivers()
  183.      */
  184.     boolean isSupported(String name);

  185. }