TimeSpanParametricAcceleration.java

/* Copyright 2002-2025 CS GROUP
 * Licensed to CS GROUP (CS) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * CS licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.orekit.forces.empirical;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import org.hipparchus.CalculusFieldElement;
import org.hipparchus.geometry.euclidean.threed.FieldVector3D;
import org.hipparchus.geometry.euclidean.threed.Vector3D;
import org.hipparchus.util.MathArrays;
import org.orekit.attitudes.AttitudeProvider;
import org.orekit.propagation.FieldSpacecraftState;
import org.orekit.propagation.SpacecraftState;
import org.orekit.time.AbsoluteDate;
import org.orekit.time.FieldAbsoluteDate;
import org.orekit.utils.ParameterDriver;
import org.orekit.utils.ParameterDriversProvider;
import org.orekit.utils.TimeSpanMap;
import org.orekit.utils.TimeSpanMap.Span;

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

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

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

    /** Simple constructor.
     * @param direction acceleration direction in overridden spacecraft frame
     * frame used for propagation (i.e. {@link SpacecraftState#getFrame()}),
     * otherwise direction is defined in spacecraft frame (i.e. using the
     * propagation {@link
     * org.orekit.propagation.Propagator#setAttitudeProvider(AttitudeProvider)
     * attitude law})
     * @param attitudeOverride provider for attitude used to compute acceleration
     * @param accelerationModel acceleration model used to compute the contribution of the empirical acceleration
     */
    public TimeSpanParametricAcceleration(final Vector3D direction,
                                          final AttitudeProvider attitudeOverride,
                                          final AccelerationModel accelerationModel) {
        this(direction, false, attitudeOverride, accelerationModel);
    }

    /** Simple constructor.
     * @param direction acceleration direction in overridden spacecraft frame
     * @param isInertial if true, direction is defined in the same inertial
     * frame used for propagation (i.e. {@link SpacecraftState#getFrame()}),
     * otherwise direction is defined in spacecraft frame (i.e. using the
     * propagation {@link
     * org.orekit.propagation.Propagator#setAttitudeProvider(AttitudeProvider)
     * attitude law})
     * @param attitudeOverride provider for attitude used to compute acceleration
     * @param accelerationModel acceleration model used to compute the contribution of the empirical acceleration
     */
    private TimeSpanParametricAcceleration(final Vector3D direction,
                                           final boolean isInertial,
                                           final AttitudeProvider attitudeOverride,
                                           final AccelerationModel accelerationModel) {
        super(direction, isInertial, attitudeOverride);
        this.accelerationModelTimeSpanMap = new TimeSpanMap<>(accelerationModel);
    }

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

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

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

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

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

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

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

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

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

        // Compute inertial direction
        final Vector3D inertialDirection = getAccelerationDirection(state);

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

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

    }

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

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

        // Compute inertial direction
        final FieldVector3D<T> inertialDirection = getAccelerationDirection(state);

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

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

    }

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

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

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

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

    }

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

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

        // Find out the indexes of the parameters in the whole array of parameters
        final List<ParameterDriver> allParameters = getParametersDrivers();
        final double[] outParameters = new double[empiricalParameterDriver.size()];
        int index = 0;
        for (int i = 0; i < allParameters.size(); i++) {
            final String driverName = allParameters.get(i).getName();
            for (ParameterDriver accDriver : empiricalParameterDriver) {
                if (accDriver.getName().equals(driverName)) {
                    outParameters[index++] = parameters[i];
                }
            }
        }
        return outParameters;
    }

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

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

        // Find out the indexes of the parameters in the whole array of parameters
        final List<ParameterDriver> allParameters = getParametersDrivers();
        final T[] outParameters = MathArrays.buildArray(date.getField(), empiricalParameterDriver.size());
        int index = 0;
        for (int i = 0; i < allParameters.size(); i++) {
            final String driverName = allParameters.get(i).getName();
            for (ParameterDriver accDriver : empiricalParameterDriver) {
                if (accDriver.getName().equals(driverName)) {
                    outParameters[index++] = parameters[i];
                }
            }
        }
        return outParameters;
    }

}