Package org.orekit.forces.drag

Class TimeSpanDragForce

java.lang.Object
org.orekit.forces.drag.AbstractDragForceModel
org.orekit.forces.drag.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 Details

    • DATE_BEFORE

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

    • DATE_AFTER

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

  • Constructor Details

    • 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

    • TimeSpanDragForce

      public TimeSpanDragForce(Atmosphere atmosphere, DragSensitive spacecraft, Atmosphere atmosphereForDerivatives, TimeScale timeScale)
      Constructor.
      Parameters:
      atmosphere - atmospheric model
      spacecraft - the initial object physical and geometric information
      atmosphereForDerivatives - atmospheric model used for partial derivatives (use fast one for performance)
      timeScale - Time scale used for the default names of the drag parameter drivers
      Since:
      14.0

  • Method Details

    • 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

    • getDragSensitiveSpan

      public TimeSpanMap.Span<DragSensitive> getDragSensitiveSpan(AbsoluteDate date)
      Get the DragSensitive TimeSpanMap.Span containing a specified date.
      Parameters:
      date - date belonging to the desired time span
      Returns:
      the DragSensitive time span containing the specified 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

    • getFirstSpan

      public TimeSpanMap.Span<DragSensitive> getFirstSpan()
      Get the first time span of the drag sensitive time span map.
      Returns:
      the first time span of the drag sensitive time span map
      Since:
      11.1

    • 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