org.orekit.forces.drag

Class TimeSpanDragForce

java.lang.Object

org.orekit.forces.AbstractForceModel

org.orekit.forces.drag.AbstractDragForceModel

org.orekit.forces.drag.TimeSpanDragForce

All Implemented Interfaces:

ForceModel, ParametersDriversProvider

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:

• Construction: constructor takes an atmospheric model and a DragSensitive model.
  This last model will be your initial DragSensitive model and it will be initially valid for the whole time line.
  The real validity of this first entry will be truncated as other DragSensitive models are added.
• Time spans: DragSensitive models are added using methods addDragSensitiveValidAfter(DragSensitive, AbsoluteDate) or addDragSensitiveValidBefore(DragSensitive, AbsoluteDate).
  Recommendations are the same than the ones in TimeSpanMap, meaning:
  • As an entry is added, it truncates the validity of the neighboring entries already present in the map;
  • The transition dates should be entered only once. Repeating a transition date will lead to unexpected result and is not supported;
  • It is advised to order your DragSensitive models chronologically when adding them to avoid any confusion.
• Naming the parameter drivers: It is strongly advised to give a custom name to the ParameterDriver(s) of each DragSensitive model that is added to the object. This will allow you keeping track of the evolution of your models.
  Different names are mandatory to differentiate the different drivers.
  If you do not specify a name, a default name will be chosen. Example for the drag coefficient:
  • Initial DragSensitive model: the driver's default name is "DragSensitive.DRAG_COEFFICIENT";
  • Using addDragSensitiveValidAfter(DragSensitive, AbsoluteDate): the driver's default name is "DragSensitive.DRAG_COEFFICIENT + DATE_AFTER + date.toString()"
  • Using addDragSensitiveValidBefore(DragSensitive, AbsoluteDate): the driver's default name is "DragSensitive.DRAG_COEFFICIENT + DATE_BEFORE + date.toString()"

Example following previous recommendations:

• Given:
  • atmosphere: an atmospheric model;
  • isotropicDrag0, 1 and 2: three IsotropicDrag models;
  • date: an AbsoluteDate.
• 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 Summary

Fields

Modifier and Type	Field and Description
static String	DATE_AFTER Prefix for dates after in the parameter drivers' name.
static String	DATE_BEFORE Prefix for dates before in the parameter drivers' name.

Constructor Summary

Constructors

Constructor and Description
TimeSpanDragForce(Atmosphere atmosphere, DragSensitive spacecraft) Constructor with default UTC time scale for the default names of the drag parameter drivers.
TimeSpanDragForce(Atmosphere atmosphere, DragSensitive spacecraft, TimeScale timeScale) Constructor.

Method Summary

Modifier and Type	Method and Description
<T extends CalculusFieldElement<T>> FieldVector3D<T>	acceleration(FieldSpacecraftState<T> s, T[] parameters) Compute acceleration.
Vector3D	acceleration(SpacecraftState s, double[] parameters) Compute acceleration.
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).
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).
TimeSpanMap<DragSensitive>	extractDragSensitiveRange(AbsoluteDate start, AbsoluteDate end) Extract a range of the DragSensitive map.
double[]	extractParameters(double[] parameters, AbsoluteDate date) Extract the proper parameter drivers' values from the array in input of the acceleration method.
<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.
DragSensitive	getDragSensitive(AbsoluteDate date) Get the DragSensitive model valid at a date.
TimeSpanMap.Span<DragSensitive>	getDragSensitiveSpan(AbsoluteDate date) Get the DragSensitive TimeSpanMap.Span containing a specified date.
Stream<EventDetector>	getEventsDetectors() Get the discrete events related to the model.
<T extends CalculusFieldElement<T>> Stream<FieldEventDetector<T>>	getFieldEventsDetectors(Field<T> field) Get the discrete events related to the model.
TimeSpanMap.Span<DragSensitive>	getFirstSpan() Get the first time span of the drag sensitive time span map.
List<ParameterDriver>	getParametersDrivers() Get the drivers for parameters.
NavigableSet<TimeSpanMap.Transition<DragSensitive>>	getTransitions() Deprecated. as of 11.1, replaced by getFirstSpan()

Methods inherited from class org.orekit.forces.drag.AbstractDragForceModel

dependsOnPositionOnly, getDSDensityWrtStateUsingFiniteDifferences, getGradientDensityWrtStateUsingFiniteDifferences, isDSStateDerivative, isGradientStateDerivative, isVariable, isVariable

Methods inherited from class org.orekit.forces.AbstractForceModel

complainIfNotSupported, getParameterDriver, isSupported

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.orekit.forces.ForceModel

addContribution, addContribution, getParameters, getParameters, init, init

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

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

getTransitions

@Deprecated
public NavigableSet<TimeSpanMap.Transition<DragSensitive>> getTransitions()

Deprecated. as of 11.1, replaced by getFirstSpan()

Get the TimeSpanMap.Transitions of the drag sensitive time span map.

Returns:

the TimeSpanMap.Transitions for the drag sensitive time span map

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

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

Returns:

acceleration in same frame as state

getEventsDetectors

public Stream<EventDetector> getEventsDetectors()

Get the discrete events related to the model.

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

Returns:

stream of events detectors

getFieldEventsDetectors

public <T extends CalculusFieldElement<T>> Stream<FieldEventDetector<T>> getFieldEventsDetectors(Field<T> field)

Get the discrete events related to the model.

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 events 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