TimeSpanParametricAcceleration.java

  1. /* Copyright 2002-2024 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.empirical;

  18. import java.util.ArrayList;
  19. import java.util.Collections;
  20. import java.util.List;
  21. import java.util.stream.Stream;

  22. import org.hipparchus.CalculusFieldElement;
  23. import org.hipparchus.Field;
  24. import org.hipparchus.geometry.euclidean.threed.FieldRotation;
  25. import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
  26. import org.hipparchus.geometry.euclidean.threed.Rotation;
  27. import org.hipparchus.geometry.euclidean.threed.Vector3D;
  28. import org.hipparchus.util.MathArrays;
  29. import org.orekit.attitudes.AttitudeProvider;
  30. import org.orekit.forces.ForceModel;
  31. import org.orekit.propagation.FieldSpacecraftState;
  32. import org.orekit.propagation.SpacecraftState;
  33. import org.orekit.propagation.events.EventDetector;
  34. import org.orekit.propagation.events.FieldEventDetector;
  35. import org.orekit.time.AbsoluteDate;
  36. import org.orekit.time.FieldAbsoluteDate;
  37. import org.orekit.utils.ParameterDriver;
  38. import org.orekit.utils.TimeSpanMap;
  39. import org.orekit.utils.TimeSpanMap.Span;

  40. /** Time span parametric acceleration model.
  41.  *  <p>
  42.  *  This class is closely related to {@link org.orekit.forces.empirical.ParametricAcceleration ParametricAcceleration} class.<br>
  43.  *  The difference is that it has a {@link TimeSpanMap} of {@link AccelerationModel} objects as attribute
  44.  *  instead of a single {@link AccelerationModel} object. <br>
  45.  *  The idea behind this model is to allow the user to design a parametric acceleration model that can see its physical parameters
  46.  *  change with time, at dates chosen by the user. <br>
  47.  *  </p>
  48.  *  <p>
  49.  *  This is a behavior that can be sought in precise orbit determination.<br>
  50.  *  Indeed for this type of application, the empirical parameters must be revalued at
  51.  *  each new orbit.
  52.  *  </p>
  53.  *  <b>Usage</b>:<ul>
  54.  *  <li><u>Construction</u>: constructor takes an acceleration direction, an attitude mode (or an inertial flag) and
  55.  *  an AccelerationModel model.<br>
  56.  *  This last model will be your initial AccelerationModel model and it will be initially valid for the whole time line.<br>
  57.  *  The real validity of this first entry will be truncated as other AccelerationModel models are added.
  58.  *  <li><u>Time spans</u>: AccelerationModel models are added using methods {@link #addAccelerationModelValidAfter(AccelerationModel, AbsoluteDate)}
  59.  *   or {@link #addAccelerationModelValidBefore(AccelerationModel, AbsoluteDate)}.<br>
  60.  *   Recommendations are the same than the ones in {@link TimeSpanMap}, meaning: <ul>
  61.  *   <li>As an entry is added, it truncates the validity of the neighboring entries already present in the map;
  62.  *   <li><b>The transition dates should be entered only once</b>. Repeating a transition date will lead to unexpected result and is not supported;
  63.  *   <li>It is advised to order your AccelerationModel models chronologically when adding them to avoid any confusion.
  64.  *   </ul>
  65.  *   <li><u>Naming the parameter drivers</u>: It is strongly advised to give a custom name to the {@link ParameterDriver}(s)
  66.  *   of each AccelerationModel model that is added to the object. This will allow you keeping track of the evolution of your models.<br>
  67.  *   Different names are mandatory to differentiate the different drivers.<br>
  68.  *   Since there is no default name for acceleration model parameters, you must handle the driver names to consider
  69.  *   different names when adding a new acceleration model.
  70.  *   </ul>
  71.  * @author Bryan Cazabonne
  72.  * @since 10.3
  73.  */
  74. public class TimeSpanParametricAcceleration implements ForceModel {

  75.     /** Prefix for dates before in the parameter drivers' name. */
  76.     public static final String DATE_BEFORE = " - Before ";

  77.     /** Prefix for dates after in the parameter drivers' name. */
  78.     public static final String DATE_AFTER = " - After ";

  79.     /** Direction of the acceleration in defining frame. */
  80.     private final Vector3D direction;

  81.     /** Flag for inertial acceleration direction. */
  82.     private final boolean isInertial;

  83.     /** The attitude to override, if set. */
  84.     private final AttitudeProvider attitudeOverride;

  85.     /** TimeSpanMap of AccelerationModel objects. */
  86.     private final TimeSpanMap<AccelerationModel> accelerationModelTimeSpanMap;

  87.     /** Simple constructor.
  88.      * @param direction acceleration direction in overridden spacecraft frame
  89.      * @param isInertial if true, direction is defined in the same inertial
  90.      * frame used for propagation (i.e. {@link SpacecraftState#getFrame()}),
  91.      * otherwise direction is defined in spacecraft frame (i.e. using the
  92.      * propagation {@link
  93.      * org.orekit.propagation.Propagator#setAttitudeProvider(AttitudeProvider)
  94.      * attitude law})
  95.      * @param accelerationModel acceleration model used to compute the contribution of the empirical acceleration
  96.      */
  97.     public TimeSpanParametricAcceleration(final Vector3D direction,
  98.                                           final boolean isInertial,
  99.                                           final AccelerationModel accelerationModel) {
  100.         this(direction, isInertial, null, accelerationModel);
  101.     }

  102.     /** Simple constructor.
  103.      * @param direction acceleration direction in overridden spacecraft frame
  104.      * frame used for propagation (i.e. {@link SpacecraftState#getFrame()}),
  105.      * otherwise direction is defined in spacecraft frame (i.e. using the
  106.      * propagation {@link
  107.      * org.orekit.propagation.Propagator#setAttitudeProvider(AttitudeProvider)
  108.      * attitude law})
  109.      * @param attitudeOverride provider for attitude used to compute acceleration
  110.      * @param accelerationModel acceleration model used to compute the contribution of the empirical acceleration
  111.      */
  112.     public TimeSpanParametricAcceleration(final Vector3D direction,
  113.                                           final AttitudeProvider attitudeOverride,
  114.                                           final AccelerationModel accelerationModel) {
  115.         this(direction, false, attitudeOverride, accelerationModel);
  116.     }

  117.     /** Simple constructor.
  118.      * @param direction acceleration direction in overridden spacecraft frame
  119.      * @param isInertial if true, direction is defined in the same inertial
  120.      * frame used for propagation (i.e. {@link SpacecraftState#getFrame()}),
  121.      * otherwise direction is defined in spacecraft frame (i.e. using the
  122.      * propagation {@link
  123.      * org.orekit.propagation.Propagator#setAttitudeProvider(AttitudeProvider)
  124.      * attitude law})
  125.      * @param attitudeOverride provider for attitude used to compute acceleration
  126.      * @param accelerationModel acceleration model used to compute the contribution of the empirical acceleration
  127.      */
  128.     private TimeSpanParametricAcceleration(final Vector3D direction,
  129.                                            final boolean isInertial,
  130.                                            final AttitudeProvider attitudeOverride,
  131.                                            final AccelerationModel accelerationModel) {
  132.         this.direction                    = direction;
  133.         this.isInertial                   = isInertial;
  134.         this.attitudeOverride             = attitudeOverride;
  135.         this.accelerationModelTimeSpanMap = new TimeSpanMap<>(accelerationModel);
  136.     }

  137.     /** {@inheritDoc} */
  138.     @Override
  139.     public void init(final SpacecraftState initialState, final AbsoluteDate target) {
  140.         accelerationModelTimeSpanMap.forEach(accelerationModel -> accelerationModel.init(initialState, target));
  141.     }

  142.     /** Add an AccelerationModel entry valid before a limit date.<br>
  143.      * <p>
  144.      * Using <code>addAccelerationModelValidBefore(entry, t)</code> will make <code>entry</code>
  145.      * valid in ]-∞, t[ (note the open bracket).
  146.      * <p>
  147.      * <b>WARNING</b>: Since there is no default name for acceleration model parameters,
  148.      * the user must handle itself the driver names to consider different names
  149.      * (i.e. different parameters) when adding a new acceleration model.
  150.      * @param accelerationModel AccelerationModel entry
  151.      * @param latestValidityDate date before which the entry is valid
  152.      * (must be different from <b>all</b> dates already used for transitions)
  153.      */
  154.     public void addAccelerationModelValidBefore(final AccelerationModel accelerationModel, final AbsoluteDate latestValidityDate) {
  155.         accelerationModelTimeSpanMap.addValidBefore(accelerationModel, latestValidityDate, false);
  156.     }

  157.     /** Add a AccelerationModel entry valid after a limit date.<br>
  158.      * <p>
  159.      * Using <code>addAccelerationModelValidAfter(entry, t)</code> will make <code>entry</code>
  160.      * valid in [t, +∞[ (note the closed bracket).
  161.      * <p>
  162.      * <b>WARNING</b>: Since there is no default name for acceleration model parameters,
  163.      * the user must handle itself the driver names to consider different names
  164.      * (i.e. different parameters) when adding a new acceleration model.
  165.      * @param accelerationModel AccelerationModel entry
  166.      * @param earliestValidityDate date after which the entry is valid
  167.      * (must be different from <b>all</b> dates already used for transitions)
  168.      */
  169.     public void addAccelerationModelValidAfter(final AccelerationModel accelerationModel, final AbsoluteDate earliestValidityDate) {
  170.         accelerationModelTimeSpanMap.addValidAfter(accelerationModel, earliestValidityDate, false);
  171.     }

  172.     /** Get the {@link AccelerationModel} model valid at a date.
  173.      * @param date the date of validity
  174.      * @return the AccelerationModel model valid at date
  175.      */
  176.     public AccelerationModel getAccelerationModel(final AbsoluteDate date) {
  177.         return accelerationModelTimeSpanMap.get(date);
  178.     }

  179.     /** Get the {@link AccelerationModel} {@link Span} containing a specified date.
  180.      * @param date date belonging to the desired time span
  181.      * @return the AccelerationModel time span containing the specified date
  182.      */
  183.     public Span<AccelerationModel> getAccelerationModelSpan(final AbsoluteDate date) {
  184.         return accelerationModelTimeSpanMap.getSpan(date);
  185.     }

  186.     /** Extract a range of the {@link AccelerationModel} map.
  187.      * <p>
  188.      * The object returned will be a new independent instance that will contain
  189.      * only the transitions that lie in the specified range.
  190.      * </p>
  191.      * See the {@link TimeSpanMap#extractRange TimeSpanMap.extractRange method} for more.
  192.      * @param start earliest date at which a transition is included in the range
  193.      * (may be set to {@link AbsoluteDate#PAST_INFINITY} to keep all early transitions)
  194.      * @param end latest date at which a transition is included in the r
  195.      * (may be set to {@link AbsoluteDate#FUTURE_INFINITY} to keep all late transitions)
  196.      * @return a new TimeSpanMap instance of AccelerationModel with all transitions restricted to the specified range
  197.      */
  198.     public TimeSpanMap<AccelerationModel> extractAccelerationModelRange(final AbsoluteDate start, final AbsoluteDate end) {
  199.         return accelerationModelTimeSpanMap.extractRange(start, end);
  200.     }

  201.     /** Get the first {@link Span time span} of the acceleration model time span map.
  202.      * @return the first {@link Span time span} of the acceleration model time span map
  203.      * @since 11.1
  204.      */
  205.     public Span<AccelerationModel> getFirstSpan() {
  206.         return accelerationModelTimeSpanMap.getFirstSpan();
  207.     }

  208.     /** {@inheritDoc} */
  209.     @Override
  210.     public boolean dependsOnPositionOnly() {
  211.         return isInertial;
  212.     }

  213.     /** {@inheritDoc} */
  214.     @Override
  215.     public Vector3D acceleration(final SpacecraftState state,
  216.                                  final double[] parameters) {

  217.         // Date
  218.         final AbsoluteDate date = state.getDate();

  219.         // Compute inertial direction
  220.         final Vector3D inertialDirection;
  221.         if (isInertial) {
  222.             // the acceleration direction is already defined in the inertial frame
  223.             inertialDirection = direction;
  224.         } else {
  225.             final Rotation rotation;
  226.             if (attitudeOverride == null) {
  227.                 // the acceleration direction is defined in spacecraft frame as set by the propagator
  228.                 rotation = state.getAttitude().getRotation();
  229.             } else {
  230.                 // the acceleration direction is defined in a dedicated frame
  231.                 rotation = attitudeOverride.getAttitudeRotation(state.getOrbit(), date, state.getFrame());
  232.             }
  233.             inertialDirection = rotation.applyInverseTo(direction);
  234.         }

  235.         // Extract the proper parameters valid at date from the input array
  236.         final double[] extractedParameters = extractParameters(parameters, date);

  237.         // Compute and return the parametric acceleration
  238.         return new Vector3D(getAccelerationModel(date).signedAmplitude(state, extractedParameters), inertialDirection);

  239.     }

  240.     /** {@inheritDoc} */
  241.     @Override
  242.     public <T extends CalculusFieldElement<T>> FieldVector3D<T> acceleration(final FieldSpacecraftState<T> state,
  243.                                                                          final T[] parameters) {

  244.         // Date
  245.         final FieldAbsoluteDate<T> date = state.getDate();

  246.         // Compute inertial direction
  247.         final FieldVector3D<T> inertialDirection;
  248.         if (isInertial) {
  249.             // the acceleration direction is already defined in the inertial frame
  250.             inertialDirection = new FieldVector3D<>(state.getDate().getField(), direction);
  251.         } else {
  252.             final FieldRotation<T> rotation;
  253.             if (attitudeOverride == null) {
  254.                 // the acceleration direction is defined in spacecraft frame as set by the propagator
  255.                 rotation = state.getAttitude().getRotation();
  256.             } else {
  257.                 // the acceleration direction is defined in a dedicated frame
  258.                 rotation = attitudeOverride.getAttitudeRotation(state.getOrbit(), date, state.getFrame());
  259.             }
  260.             inertialDirection = rotation.applyInverseTo(direction);
  261.         }

  262.         // Extract the proper parameters valid at date from the input array
  263.         final T[] extractedParameters = extractParameters(parameters, date);

  264.         // Compute and return the parametric acceleration
  265.         return new FieldVector3D<>(getAccelerationModel(date.toAbsoluteDate()).signedAmplitude(state, extractedParameters), inertialDirection);

  266.     }

  267.     /** {@inheritDoc} */
  268.     @Override
  269.     public Stream<EventDetector> getEventDetectors() {
  270.         return Stream.empty();
  271.     }

  272.     /** {@inheritDoc} */
  273.     @Override
  274.     public <T extends CalculusFieldElement<T>> Stream<FieldEventDetector<T>> getFieldEventDetectors(final Field<T> field) {
  275.         return Stream.empty();
  276.     }

  277.     /** {@inheritDoc}
  278.      * <p>
  279.      * All the parameter drivers of all AccelerationModel models are returned in an array.
  280.      * Models are ordered chronologically.
  281.      * </p>
  282.      */
  283.     @Override
  284.     public List<ParameterDriver> getParametersDrivers() {

  285.         // Get all transitions from the TimeSpanMap
  286.         final List<ParameterDriver> listParameterDrivers = new ArrayList<>();

  287.         // Loop on the spans
  288.         for (Span<AccelerationModel> span = getFirstSpan(); span != null; span = span.next()) {
  289.             // Add all the parameter drivers of the time span
  290.             for (ParameterDriver driver : span.getData().getParametersDrivers()) {
  291.                 // Add the driver only if the name does not exist already
  292.                 if (!findByName(listParameterDrivers, driver.getName())) {
  293.                     listParameterDrivers.add(driver);
  294.                 }
  295.             }
  296.         }

  297.         // Return an array of parameter drivers with no duplicated name
  298.         return Collections.unmodifiableList(listParameterDrivers);

  299.     }

  300.     /** Extract the proper parameter drivers' values from the array in input of the
  301.      * {@link #acceleration(SpacecraftState, double[]) acceleration} method.
  302.      *  Parameters are filtered given an input date.
  303.      * @param parameters the input parameters array
  304.      * @param date the date
  305.      * @return the parameters given the date
  306.      */
  307.     public double[] extractParameters(final double[] parameters, final AbsoluteDate date) {

  308.         // Get the acceleration model parameter drivers of the date
  309.         final List<ParameterDriver> empiricalParameterDriver = getAccelerationModel(date).getParametersDrivers();

  310.         // Find out the indexes of the parameters in the whole array of parameters
  311.         final List<ParameterDriver> allParameters = getParametersDrivers();
  312.         final double[] outParameters = new double[empiricalParameterDriver.size()];
  313.         int index = 0;
  314.         for (int i = 0; i < allParameters.size(); i++) {
  315.             final String driverName = allParameters.get(i).getName();
  316.             for (ParameterDriver accDriver : empiricalParameterDriver) {
  317.                 if (accDriver.getName().equals(driverName)) {
  318.                     outParameters[index++] = parameters[i];
  319.                 }
  320.             }
  321.         }
  322.         return outParameters;
  323.     }

  324.     /** Extract the proper parameter drivers' values from the array in input of the
  325.      * {@link #acceleration(FieldSpacecraftState, CalculusFieldElement[]) acceleration} method.
  326.      *  Parameters are filtered given an input date.
  327.      * @param parameters the input parameters array
  328.      * @param date the date
  329.      * @param <T> extends CalculusFieldElement
  330.      * @return the parameters given the date
  331.      */
  332.     public <T extends CalculusFieldElement<T>> T[] extractParameters(final T[] parameters,
  333.                                                                  final FieldAbsoluteDate<T> date) {

  334.         // Get the acceleration parameter drivers of the date
  335.         final List<ParameterDriver> empiricalParameterDriver = getAccelerationModel(date.toAbsoluteDate()).getParametersDrivers();

  336.         // Find out the indexes of the parameters in the whole array of parameters
  337.         final List<ParameterDriver> allParameters = getParametersDrivers();
  338.         final T[] outParameters = MathArrays.buildArray(date.getField(), empiricalParameterDriver.size());
  339.         int index = 0;
  340.         for (int i = 0; i < allParameters.size(); i++) {
  341.             final String driverName = allParameters.get(i).getName();
  342.             for (ParameterDriver accDriver : empiricalParameterDriver) {
  343.                 if (accDriver.getName().equals(driverName)) {
  344.                     outParameters[index++] = parameters[i];
  345.                 }
  346.             }
  347.         }
  348.         return outParameters;
  349.     }

  350.     /** Find if a parameter driver with a given name already exists in a list of parameter drivers.
  351.      * @param driversList the list of parameter drivers
  352.      * @param name the parameter driver's name to filter with
  353.      * @return true if the name was found, false otherwise
  354.      */
  355.     private boolean findByName(final List<ParameterDriver> driversList, final String name) {
  356.         for (final ParameterDriver d : driversList) {
  357.             if (d.getName().equals(name)) {
  358.                 return true;
  359.             }
  360.         }
  361.         return false;
  362.     }

  363. }