Package org.orekit.forces.drag

Class TimeSpanDragForce

  • All Implemented Interfaces:
    ForceModel, EventDetectorsProvider, ParameterDriversProvider
    public class TimeSpanDragForce
extends AbstractDragForceModel
    Time span atmospheric drag force model.

    This class is closely related to DragForce class.
    The difference is that it has a TimeSpanMap of DragSensitive objects as attribute instead of a single DragSensitive object.
    The idea behind this model is to allow the user to design a drag force model that can see its physical parameters (drag coefficient and lift ratio) change with time, at dates chosen by the user.

    This is a behavior that can be sought in operational orbit determination.
    Indeed the solar activity has a strong influence on the local atmospheric density, and thus on the drag force effect.
    Solar activity is a physical phenomenon that is difficult to model and predict.
    The errors induced by this incomplete modeling can be estimated through the drag coefficients.
    Being able to define and estimate drag coefficients depending on user-chosen dates in a piecewise fashion allows for a better modeling of solar activity uncertainties.

    A typical operational use case is to have a daily solar activity with three-hourly magnetic indexes provided by an international organization (NOAA for example).
    Given this input, a user can define a piecewise drag force model with daily or three-hourly drag coefficients.
    Each timed coefficient will absorb a part of the uncertainties in the solar activity and will allow for a more accurate orbit determination

    Usage: Example following previous recommendations:
    • Given:
    • Name the drivers:
      isotropicDrag0.getDragParametersDrivers()[0].setName = "Cd0";
      isotropicDrag1.getDragParametersDrivers()[0].setName = "Cd1";
      isotropicDrag2.getDragParametersDrivers()[0].setName = "Cd2";
    • Initialize the model:
      TimeSpanDragForce force = new TimeSpanDragForce(atmosphere, isotropicDrag0);
    • Set the second and third model one Julian day apart each:
      force.addDragSensitiveValidAfter(isotropicDrag1, date.shiftedBy(Constants.JULIAN_DAY));
      force.addDragSensitiveValidAfter(isotropicDrag2, date.shiftedBy(2 * Constants.JULIAN_DAY));
    • With this, your model will have the following properties:
      • t in ]-∞, date + 1 day [ / Cd = Cd0
      • t in [date + 1 day, date + 2days [ / Cd = Cd1
      • t in [date + 2 days, +∞ [ / Cd = Cd2

    Warning:
    The TimeSpanDragForce model is versatile and you could end up with non-physical modeling.
    For example you could add 2 IsotropicDrag models with different areas, or one IsotropicDrag model and then one BoxAndSolarArraySpacecraft model.
    It is up to you to ensure that your models are consistent with each other, Orekit will not perform any check for that.

    Since:
    10.2
    Author:
    Maxime Journot

    • Field Detail

      • DATE_BEFORE

        public static final String DATE_BEFORE
        Prefix for dates before in the parameter drivers' name.
        See Also:
        Constant Field Values

      • DATE_AFTER

        public static final String DATE_AFTER
        Prefix for dates after in the parameter drivers' name.
        See Also:
        Constant Field Values

    • Constructor Detail

      • TimeSpanDragForce

        @DefaultDataContext
public TimeSpanDragForce​(Atmosphere atmosphere,
                         DragSensitive spacecraft)
        Constructor with default UTC time scale for the default names of the drag parameter drivers.
        Parameters:
        atmosphere - atmospheric model
        spacecraft - Time scale used for the default names of the drag parameter drivers

      • TimeSpanDragForce

        public TimeSpanDragForce​(Atmosphere atmosphere,
                         DragSensitive spacecraft,
                         TimeScale timeScale)
        Constructor.
        Parameters:
        atmosphere - atmospheric model
        spacecraft - the initial object physical and geometric information
        timeScale - Time scale used for the default names of the drag parameter drivers

    • Method Detail

      • addDragSensitiveValidBefore

        public void addDragSensitiveValidBefore​(DragSensitive dragSensitive,
                                        AbsoluteDate latestValidityDate)
        Add a DragSensitive entry valid before a limit date.
        Using addDragSensitiveValidBefore(entry, t) will make entry valid in ]-∞, t[ (note the open bracket).
        Parameters:
        dragSensitive - DragSensitive entry
        latestValidityDate - date before which the entry is valid (must be different from all dates already used for transitions)

      • addDragSensitiveValidAfter

        public void addDragSensitiveValidAfter​(DragSensitive dragSensitive,
                                       AbsoluteDate earliestValidityDate)
        Add a DragSensitive entry valid after a limit date.
        Using addDragSensitiveValidAfter(entry, t) will make entry valid in [t, +∞[ (note the closed bracket).
        Parameters:
        dragSensitive - DragSensitive entry
        earliestValidityDate - date after which the entry is valid (must be different from all dates already used for transitions)

      • getDragSensitive

        public DragSensitive getDragSensitive​(AbsoluteDate date)
        Get the DragSensitive model valid at a date.
        Parameters:
        date - the date of validity
        Returns:
        the DragSensitive model valid at date

      • extractDragSensitiveRange

        public TimeSpanMap<DragSensitive> extractDragSensitiveRange​(AbsoluteDate start,
                                                            AbsoluteDate end)
        Extract a range of the DragSensitive map.

        The object returned will be a new independent instance that will contain only the transitions that lie in the specified range.

        See the TimeSpanMap.extractRange method for more.
        Parameters:
        start - earliest date at which a transition is included in the range (may be set to AbsoluteDate.PAST_INFINITY to keep all early transitions)
        end - latest date at which a transition is included in the r (may be set to AbsoluteDate.FUTURE_INFINITY to keep all late transitions)
        Returns:
        a new TimeSpanMap instance of DragSensitive with all transitions restricted to the specified range

      • acceleration

        public Vector3D acceleration​(SpacecraftState s,
                             double[] parameters)
        Compute acceleration.
        Parameters:
        s - current state information: date, kinematics, attitude
        parameters - values of the force model parameters at state date, only 1 value for each parameterDriver
        Returns:
        acceleration in same frame as state

      • acceleration

        public <T extends CalculusFieldElement<T>> FieldVector3D<T> acceleration​(FieldSpacecraftState<T> s,
                                                                         T[] parameters)
        Compute acceleration.
        Type Parameters:
        T - type of the elements
        Parameters:
        s - current state information: date, kinematics, attitude
        parameters - values of the force model parameters at state date, only 1 value for each parameterDriver
        Returns:
        acceleration in same frame as state

      • getEventDetectors

        public Stream<EventDetector> getEventDetectors()
        Get the discrete events related to the model.

        This method is not intended to be called several time, only once by a propagator, as it has the side effect of rebuilding the events detectors when called.

        A date detector is used to cleanly stop the propagator and reset the state derivatives at transition dates.

        Returns:
        stream of event detectors

      • getFieldEventDetectors

        public <T extends CalculusFieldElement<T>> Stream<FieldEventDetector<T>> getFieldEventDetectors​(Field<T> field)
        Get the discrete events related to the model.

        This method is not intended to be called several time, only once by a propagator, as it has the side effect of rebuilding the events detectors when called.

        A date detector is used to cleanly stop the propagator and reset the state derivatives at transition dates.

        Type Parameters:
        T - extends CalculusFieldElement<T>
        Parameters:
        field - field to which the state belongs
        Returns:
        stream of event detectors

      • getParametersDrivers

        public List<ParameterDriver> getParametersDrivers()
        Get the drivers for parameters.

        All the parameter drivers of all DragSensitive models are returned in an array. Models are ordered chronologically.

        Returns:
        drivers for parameters

      • extractParameters

        public double[] extractParameters​(double[] parameters,
                                  AbsoluteDate date)
        Extract the proper parameter drivers' values from the array in input of the acceleration method. Parameters are filtered given an input date.
        Parameters:
        parameters - the input parameters array
        date - the date
        Returns:
        the parameters given the date

      • extractParameters

        public <T extends CalculusFieldElement<T>> T[] extractParameters​(T[] parameters,
                                                                 FieldAbsoluteDate<T> date)
        Extract the proper parameter drivers' values from the array in input of the acceleration method. Parameters are filtered given an input date.
        Type Parameters:
        T - extends CalculusFieldElement
        Parameters:
        parameters - the input parameters array
        date - the date
        Returns:
        the parameters given the date