ForceModel.java

  1. /* Copyright 2002-2025 CS GROUP
  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.forces;

  19. import java.util.stream.Stream;

  21. import org.hipparchus.CalculusFieldElement;
  22. import org.hipparchus.Field;
  23. import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
  24. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  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.EventDetectorsProvider;
  29. import org.orekit.propagation.events.FieldEventDetector;
  30. import org.orekit.propagation.numerical.FieldTimeDerivativesEquations;
  31. import org.orekit.propagation.numerical.TimeDerivativesEquations;
  32. import org.orekit.time.AbsoluteDate;
  33. import org.orekit.time.FieldAbsoluteDate;
  34. import org.orekit.utils.ParameterDriversProvider;

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

  68.     /**
  69.      * Initialize the force model at the start of propagation. This method will be called
  70.      * before any calls to {@link #addContribution(SpacecraftState, TimeDerivativesEquations)},
  71.      * {@link #addContribution(FieldSpacecraftState, FieldTimeDerivativesEquations)},
  72.      * {@link #acceleration(SpacecraftState, double[])} or {@link #acceleration(FieldSpacecraftState, CalculusFieldElement[])}
  73.      *
  74.      * <p> The default implementation of this method does nothing.</p>
  75.      *
  76.      * @param initialState spacecraft state at the start of propagation.
  77.      * @param target       date of propagation. Not equal to {@code initialState.getDate()}.
  78.      */
  79.     default void init(SpacecraftState initialState, AbsoluteDate target) {
  80.     }

  82.     /**
  83.      * Initialize the force model at the start of propagation. This method will be called
  84.      * before any calls to {@link #addContribution(SpacecraftState, TimeDerivativesEquations)},
  85.      * {@link #addContribution(FieldSpacecraftState, FieldTimeDerivativesEquations)},
  86.      * {@link #acceleration(SpacecraftState, double[])} or {@link #acceleration(FieldSpacecraftState, CalculusFieldElement[])}
  87.      *
  88.      * <p> The default implementation of this method does nothing.</p>
  89.      *
  90.      * @param initialState spacecraft state at the start of propagation.
  91.      * @param target       date of propagation. Not equal to {@code initialState.getDate()}.
  92.      * @param <T> type of the elements
  93.      */
  94.     default <T extends CalculusFieldElement<T>> void init(FieldSpacecraftState<T> initialState, FieldAbsoluteDate<T> target) {
  95.         init(initialState.toSpacecraftState(), target.toAbsoluteDate());
  96.     }

  98.     /** {@inheritDoc}.*/
  99.     @Override
  100.     default Stream<EventDetector> getEventDetectors() {
  101.         return getEventDetectors(getParametersDrivers());
  102.     }

  104.     /** {@inheritDoc}.*/
  105.     @Override
  106.     default <T extends CalculusFieldElement<T>> Stream<FieldEventDetector<T>> getFieldEventDetectors(Field<T> field) {
  107.         return getFieldEventDetectors(field, getParametersDrivers());
  108.     }

  110.     /** Compute the contribution of the force model to the perturbing
  111.      * acceleration.
  112.      * <p>
  113.      * The default implementation simply adds the {@link #acceleration(SpacecraftState, double[]) acceleration}
  114.      * as a non-Keplerian acceleration.
  115.      * </p>
  116.      * @param s current state information: date, kinematics, attitude
  117.      * @param adder object where the contribution should be added
  118.      */
  119.     default void addContribution(SpacecraftState s, TimeDerivativesEquations adder) {
  120.         final double[] parameters = getParameters(s.getDate());
  121.         adder.addNonKeplerianAcceleration(acceleration(s, getParameters(s.getDate())));
  122.         adder.addMassDerivative(getMassDerivative(s, parameters));
  123.     }

  125.     /** Compute the contribution of the force model to the perturbing
  126.      * acceleration.
  127.      * @param s current state information: date, kinematics, attitude
  128.      * @param adder object where the contribution should be added
  129.      * @param <T> type of the elements
  130.      */
  131.     default <T extends CalculusFieldElement<T>> void addContribution(FieldSpacecraftState<T> s, FieldTimeDerivativesEquations<T> adder) {
  132.         final T[] parameters = getParameters(s.getDate().getField(), s.getDate());
  133.         adder.addNonKeplerianAcceleration(acceleration(s, parameters));
  134.         adder.addMassDerivative(getMassDerivative(s, parameters));
  135.     }

  137.     /**
  138.      * Compute the mass rate. Zero by default.
  139.      * @param state current state information: date, kinematics, attitude
  140.      * @param parameters values of the force model parameters at state date
  141.      * @return mass rate (kg/s)
  142.      * @since 13.1
  143.      */
  144.     default double getMassDerivative(SpacecraftState state, double[] parameters) {
  145.         return 0.;
  146.     }

  148.     /**
  149.      * Compute the mass rate. Zero by default.
  150.      * @param <T> field type
  151.      * @param state current state information: date, kinematics, attitude
  152.      * @param parameters values of the force model parameters at state date
  153.      * @return mass rate (kg/s)
  154.      * @since 13.1
  155.      */
  156.     default <T extends CalculusFieldElement<T>> T getMassDerivative(FieldSpacecraftState<T> state, T[] parameters) {
  157.         return state.getMass().getField().getZero();
  158.     }

  160.     /** Check if force model depends on position only at a given, fixed date.
  161.      * @return true if force model depends on position only, false
  162.      * if it depends on velocity, either directly or due to a dependency
  163.      * on attitude
  164.      * @since 9.0
  165.      */
  166.     boolean dependsOnPositionOnly();

  168.     /** Check if force model depends on attitude's rotation rate or acceleration at a given, fixed date.
  169.      * If false, it essentially means that at most the attitude's rotation is used when computing the acceleration vector.
  170.      * The default implementation returns false as common forces do not.
  171.      * @return true if force model depends on attitude derivatives
  172.      * @since 12.1
  173.      */
  174.     default boolean dependsOnAttitudeRate() {
  175.         return false;
  176.     }

  178.     /** Compute acceleration.
  179.      * @param s current state information: date, kinematics, attitude
  180.      * @param parameters values of the force model parameters at state date,
  181.      * only 1 value for each parameterDriver
  182.      * @return acceleration in same frame as state
  183.      * @since 9.0
  184.      */
  185.     Vector3D acceleration(SpacecraftState s, double[] parameters);

  187.     /** Compute acceleration.
  188.      * @param s current state information: date, kinematics, attitude
  189.      * @param parameters values of the force model parameters at state date,
  190.      * only 1 value for each parameterDriver
  191.      * @return acceleration in same frame as state
  192.      * @param <T> type of the elements
  193.      * @since 9.0
  194.      */
  195.     <T extends CalculusFieldElement<T>> FieldVector3D<T> acceleration(FieldSpacecraftState<T> s, T[] parameters);
  196. }
Created with JaCoCo 0.8.12.202403310830