Class SpacecraftState
- java.lang.Object
-
- org.orekit.propagation.SpacecraftState
-
- All Implemented Interfaces:
TimeShiftable<SpacecraftState>
,TimeStamped
public class SpacecraftState extends Object implements TimeStamped, TimeShiftable<SpacecraftState>
This class is the representation of a complete state holding orbit, attitude and mass information at a given date, meant primarily for propagation.It contains an
Orbit
, or anAbsolutePVCoordinates
if there is no definite central body, plus the current mass and attitude at the intrinsicAbsoluteDate
. Quantities are guaranteed to be consistent in terms of date and reference frame. The spacecraft state may also contain additional data, which are simply named.The state can be slightly shifted to close dates. This actual shift varies between
Orbit
andAbsolutePVCoordinates
. For attitude it is a linear extrapolation taking the spin rate into account and no mass change. It is not intended as a replacement for proper orbit and attitude propagation but should be sufficient for either small time shifts or coarse accuracy.The instance
SpacecraftState
is guaranteed to be immutable.- Author:
- Fabien Maussion, Véronique Pommier-Maurussane, Luc Maisonobe
- See Also:
NumericalPropagator
-
-
Field Summary
Fields Modifier and Type Field Description static double
DEFAULT_MASS
Default mass.
-
Constructor Summary
Constructors Constructor Description SpacecraftState(Orbit orbit)
Build a spacecraft state from orbit only.SpacecraftState(Orbit orbit, double mass)
Deprecated.since 13.0, use withXXXSpacecraftState(Orbit orbit, Attitude attitude)
Build a spacecraft state from orbit and attitude.SpacecraftState(Orbit orbit, Attitude attitude, double mass)
Deprecated.since 13.0, use withXXXSpacecraftState(Orbit orbit, Attitude attitude, double mass, DataDictionary additional, DoubleArrayDictionary additionalDot)
Build a spacecraft state from orbit, attitude, mass, additional states and derivatives.SpacecraftState(AbsolutePVCoordinates absPva)
Build a spacecraft state from position-velocity-acceleration only.SpacecraftState(AbsolutePVCoordinates absPva, double mass)
Deprecated.since 13.0, use withXXXSpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude)
Build a spacecraft state from position-velocity-acceleration and attitude.SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass)
Deprecated.since 13.0, use withXXXSpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass, DataDictionary additional, DoubleArrayDictionary additionalDot)
Build a spacecraft state from position-velocity-acceleration, attitude, mass and additional states and derivatives.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description SpacecraftState
addAdditionalData(String name, Object value)
Add an additional data.SpacecraftState
addAdditionalStateDerivative(String name, double... value)
Add an additional state derivative.void
ensureCompatibleAdditionalStates(SpacecraftState state)
Check if two instances have the same set of additional states available.AbsolutePVCoordinates
getAbsPVA()
Get the absolute position-velocity-acceleration.Object
getAdditionalData(String name)
Get an additional data.DataDictionary
getAdditionalDataValues()
Get an unmodifiable map of additional data.double[]
getAdditionalState(String name)
Get an additional state.double[]
getAdditionalStateDerivative(String name)
Get an additional state derivative.DoubleArrayDictionary
getAdditionalStatesDerivatives()
Get an unmodifiable map of additional states derivatives.Attitude
getAttitude()
Get the attitude.AbsoluteDate
getDate()
Get the date.Frame
getFrame()
Get the defining frame.double
getMass()
Gets the current mass.Orbit
getOrbit()
Get the current orbit.Vector3D
getPosition()
Get the position in orbit definition frame.Vector3D
getPosition(Frame outputFrame)
Get the position in given output frame.TimeStampedPVCoordinates
getPVCoordinates()
Get theTimeStampedPVCoordinates
in orbit definition frame.TimeStampedPVCoordinates
getPVCoordinates(Frame outputFrame)
Get theTimeStampedPVCoordinates
in given output frame.boolean
hasAdditionalData(String name)
Check if an additional data is available.boolean
hasAdditionalStateDerivative(String name)
Check if an additional state derivative is available.boolean
isOrbitDefined()
Check if the state contains an orbit part.SpacecraftState
shiftedBy(double dt)
Get a time-shifted state.SpacecraftState
shiftedBy(TimeOffset dt)
Get a time-shifted state.StaticTransform
toStaticTransform()
Compute the static transform from state defining frame to spacecraft frame.String
toString()
Transform
toTransform()
Compute the transform from state defining frame to spacecraft frame.SpacecraftState
withAdditionalData(DataDictionary dataDictionary)
Create a new instance with input additional data.SpacecraftState
withAdditionalStatesDerivatives(DoubleArrayDictionary additionalStateDerivatives)
Create a new instance with input additional data.SpacecraftState
withAttitude(Attitude newAttitude)
Create a new instance with input attitude.SpacecraftState
withMass(double newMass)
Create a new instance with input mass.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface org.orekit.time.TimeStamped
durationFrom
-
-
-
-
Field Detail
-
DEFAULT_MASS
public static final double DEFAULT_MASS
Default mass.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
SpacecraftState
public SpacecraftState(Orbit orbit)
Build a spacecraft state from orbit only.Attitude and mass are set to unspecified non-null arbitrary values.
- Parameters:
orbit
- the orbit
-
SpacecraftState
public SpacecraftState(Orbit orbit, Attitude attitude) throws IllegalArgumentException
Build a spacecraft state from orbit and attitude. Kept for performance.Mass is set to an unspecified non-null arbitrary value.
- Parameters:
orbit
- the orbitattitude
- attitude- Throws:
IllegalArgumentException
- if orbit and attitude dates or frames are not equal
-
SpacecraftState
@Deprecated public SpacecraftState(Orbit orbit, double mass)
Deprecated.since 13.0, use withXXXCreate a new instance from orbit and mass.Attitude law is set to an unspecified default attitude.
- Parameters:
orbit
- the orbitmass
- the mass (kg)
-
SpacecraftState
@Deprecated public SpacecraftState(Orbit orbit, Attitude attitude, double mass) throws IllegalArgumentException
Deprecated.since 13.0, use withXXXBuild a spacecraft state from orbit, attitude and mass.- Parameters:
orbit
- the orbitattitude
- attitudemass
- the mass (kg)- Throws:
IllegalArgumentException
- if orbit and attitude dates or frames are not equal
-
SpacecraftState
public SpacecraftState(Orbit orbit, Attitude attitude, double mass, DataDictionary additional, DoubleArrayDictionary additionalDot) throws IllegalArgumentException
Build a spacecraft state from orbit, attitude, mass, additional states and derivatives.- Parameters:
orbit
- the orbitattitude
- attitudemass
- the mass (kg)additional
- additional data (may be null if no additional states are available)additionalDot
- additional states derivatives (may be null if no additional states derivatives are available)- Throws:
IllegalArgumentException
- if orbit and attitude dates or frames are not equal- Since:
- 13.0
-
SpacecraftState
public SpacecraftState(AbsolutePVCoordinates absPva)
Build a spacecraft state from position-velocity-acceleration only.Attitude and mass are set to unspecified non-null arbitrary values.
- Parameters:
absPva
- position-velocity-acceleration
-
SpacecraftState
public SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude) throws IllegalArgumentException
Build a spacecraft state from position-velocity-acceleration and attitude. Kept for performance.Mass is set to an unspecified non-null arbitrary value.
- Parameters:
absPva
- position-velocity-accelerationattitude
- attitude- Throws:
IllegalArgumentException
- if orbit and attitude dates or frames are not equal
-
SpacecraftState
@Deprecated public SpacecraftState(AbsolutePVCoordinates absPva, double mass)
Deprecated.since 13.0, use withXXXCreate a new instance from position-velocity-acceleration and mass.Attitude law is set to an unspecified default attitude.
- Parameters:
absPva
- position-velocity-accelerationmass
- the mass (kg)
-
SpacecraftState
@Deprecated public SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass) throws IllegalArgumentException
Deprecated.since 13.0, use withXXXBuild a spacecraft state from position-velocity-acceleration, attitude and mass.- Parameters:
absPva
- position-velocity-accelerationattitude
- attitudemass
- the mass (kg)- Throws:
IllegalArgumentException
- if orbit and attitude dates or frames are not equal
-
SpacecraftState
public SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass, DataDictionary additional, DoubleArrayDictionary additionalDot) throws IllegalArgumentException
Build a spacecraft state from position-velocity-acceleration, attitude, mass and additional states and derivatives.- Parameters:
absPva
- position-velocity-accelerationattitude
- attitudemass
- the mass (kg)additional
- additional data (may be null if no additional data are available)additionalDot
- additional states derivatives(may be null if no additional states derivatives are available)- Throws:
IllegalArgumentException
- if orbit and attitude dates or frames are not equal- Since:
- 13.0
-
-
Method Detail
-
withMass
public SpacecraftState withMass(double newMass)
Create a new instance with input mass.- Parameters:
newMass
- mass- Returns:
- new state
- Since:
- 13.0
-
withAttitude
public SpacecraftState withAttitude(Attitude newAttitude)
Create a new instance with input attitude.- Parameters:
newAttitude
- attitude- Returns:
- new state
- Since:
- 13.0
-
withAdditionalData
public SpacecraftState withAdditionalData(DataDictionary dataDictionary)
Create a new instance with input additional data.- Parameters:
dataDictionary
- additional data- Returns:
- new state
- Since:
- 13.0
-
withAdditionalStatesDerivatives
public SpacecraftState withAdditionalStatesDerivatives(DoubleArrayDictionary additionalStateDerivatives)
Create a new instance with input additional data.- Parameters:
additionalStateDerivatives
- additional state derivatives- Returns:
- new state
- Since:
- 13.0
-
addAdditionalData
public SpacecraftState addAdditionalData(String name, Object value)
Add an additional data.SpacecraftState
instances are immutable, so this method does not change the instance, but rather creates a new instance, which has the same orbit, attitude, mass and additional states as the original instance, except it also has the specified state. If the original instance already had an additional data with the same name, it will be overridden. If it did not have any additional state with that name, the new instance will have one more additional state than the original instance.- Parameters:
name
- name of the additional data (names containing "orekit" with any case are reserved for the library internal use)value
- value of the additional data- Returns:
- a new instance, with the additional data added
- Since:
- 13.0
- See Also:
hasAdditionalData(String)
,getAdditionalData(String)
,getAdditionalDataValues()
-
addAdditionalStateDerivative
public SpacecraftState addAdditionalStateDerivative(String name, double... value)
Add an additional state derivative.SpacecraftState
instances are immutable, so this method does not change the instance, but rather creates a new instance, which has the same components as the original instance, except it also has the specified state derivative. If the original instance already had an additional state derivative with the same name, it will be overridden. If it did not have any additional state derivative with that name, the new instance will have one more additional state derivative than the original instance.- Parameters:
name
- name of the additional state derivative (names containing "orekit" with any case are reserved for the library internal use)value
- value of the additional state derivative- Returns:
- a new instance, with the additional state added
- Since:
- 11.1
- See Also:
hasAdditionalStateDerivative(String)
,getAdditionalStateDerivative(String)
,getAdditionalStatesDerivatives()
-
isOrbitDefined
public boolean isOrbitDefined()
Check if the state contains an orbit part.A state contains either an
absolute position-velocity-acceleration
or anorbit
.- Returns:
- true if state contains an orbit (in which case
getOrbit()
will not throw an exception), or false if the state contains an absolut position-velocity-acceleration (in which casegetAbsPVA()
will not throw an exception)
-
shiftedBy
public SpacecraftState shiftedBy(double dt)
Get a time-shifted state.The state can be slightly shifted to close dates. This shift is based on simple models. For orbits, the model is a Keplerian one if no derivatives are available in the orbit, or Keplerian plus quadratic effect of the non-Keplerian acceleration if derivatives are available. For attitude, a polynomial model is used. Neither mass nor additional states change. Shifting is not intended as a replacement for proper orbit and attitude propagation but should be sufficient for small time shifts or coarse accuracy.
As a rough order of magnitude, the following table shows the extrapolation errors obtained between this simple shift method and an
numerical propagator
for a low Earth Sun Synchronous Orbit, with a 20x20 gravity field, Sun and Moon third bodies attractions, drag and solar radiation pressure. Beware that these results will be different for other orbits.Extrapolation Error interpolation time (s) position error without derivatives (m) position error with derivatives (m) 60 18 1.1 120 72 9.1 300 447 140 600 1601 1067 900 3141 3307 - Specified by:
shiftedBy
in interfaceTimeShiftable<SpacecraftState>
- Parameters:
dt
- time shift in seconds- Returns:
- a new state, shifted with respect to the instance (which is immutable) except for the mass and additional states which stay unchanged
-
shiftedBy
public SpacecraftState shiftedBy(TimeOffset dt)
Get a time-shifted state.The state can be slightly shifted to close dates. This shift is based on simple models. For orbits, the model is a Keplerian one if no derivatives are available in the orbit, or Keplerian plus quadratic effect of the non-Keplerian acceleration if derivatives are available. For attitude, a polynomial model is used. Neither mass nor additional states change. Shifting is not intended as a replacement for proper orbit and attitude propagation but should be sufficient for small time shifts or coarse accuracy.
As a rough order of magnitude, the following table shows the extrapolation errors obtained between this simple shift method and an
numerical propagator
for a low Earth Sun Synchronous Orbit, with a 20x20 gravity field, Sun and Moon third bodies attractions, drag and solar radiation pressure. Beware that these results will be different for other orbits.Extrapolation Error interpolation time (s) position error without derivatives (m) position error with derivatives (m) 60 18 1.1 120 72 9.1 300 447 140 600 1601 1067 900 3141 3307 - Specified by:
shiftedBy
in interfaceTimeShiftable<SpacecraftState>
- Parameters:
dt
- time shift in seconds- Returns:
- a new state, shifted with respect to the instance (which is immutable) except for the mass and additional states which stay unchanged
- Since:
- 13.0
-
getAbsPVA
public AbsolutePVCoordinates getAbsPVA() throws OrekitIllegalStateException
Get the absolute position-velocity-acceleration.A state contains either an
absolute position-velocity-acceleration
or anorbit
. Which one is present can be checked usingisOrbitDefined()
.- Returns:
- absolute position-velocity-acceleration
- Throws:
OrekitIllegalStateException
- if position-velocity-acceleration is null, which mean the state rather contains anOrbit
- See Also:
isOrbitDefined()
,getOrbit()
-
getOrbit
public Orbit getOrbit() throws OrekitIllegalStateException
Get the current orbit.A state contains either an
absolute position-velocity-acceleration
or anorbit
. Which one is present can be checked usingisOrbitDefined()
.- Returns:
- the orbit
- Throws:
OrekitIllegalStateException
- if orbit is null, which means the state rather contains anabsolute position-velocity-acceleration
- See Also:
isOrbitDefined()
,getAbsPVA()
-
getDate
public AbsoluteDate getDate()
Get the date.- Specified by:
getDate
in interfaceTimeStamped
- Returns:
- date attached to the object
-
getFrame
public Frame getFrame()
Get the defining frame.- Returns:
- the frame in which state is defined
-
hasAdditionalData
public boolean hasAdditionalData(String name)
Check if an additional data is available.- Parameters:
name
- name of the additional data- Returns:
- true if the additional data is available
- See Also:
addAdditionalData(String, Object)
,getAdditionalState(String)
,getAdditionalData(String)
,getAdditionalDataValues()
-
hasAdditionalStateDerivative
public boolean hasAdditionalStateDerivative(String name)
Check if an additional state derivative is available.- Parameters:
name
- name of the additional state derivative- Returns:
- true if the additional state derivative is available
- Since:
- 11.1
- See Also:
addAdditionalStateDerivative(String, double[])
,getAdditionalStateDerivative(String)
,getAdditionalStatesDerivatives()
-
ensureCompatibleAdditionalStates
public void ensureCompatibleAdditionalStates(SpacecraftState state) throws MathIllegalStateException
Check if two instances have the same set of additional states available.Only the names and dimensions of the additional states are compared, not their values.
- Parameters:
state
- state to compare to instance- Throws:
MathIllegalStateException
- if an additional state does not have the same dimension in both states
-
getAdditionalState
public double[] getAdditionalState(String name)
Get an additional state.- Parameters:
name
- name of the additional state- Returns:
- value of the additional state
- See Also:
hasAdditionalData(String)
,getAdditionalDataValues()
-
getAdditionalData
public Object getAdditionalData(String name)
Get an additional data.- Parameters:
name
- name of the additional state- Returns:
- value of the additional state
- Since:
- 13.0
- See Also:
addAdditionalData(String, Object)
,hasAdditionalData(String)
,getAdditionalDataValues()
-
getAdditionalStateDerivative
public double[] getAdditionalStateDerivative(String name)
Get an additional state derivative.- Parameters:
name
- name of the additional state derivative- Returns:
- value of the additional state derivative
- Since:
- 11.1
- See Also:
addAdditionalStateDerivative(String, double[])
,hasAdditionalStateDerivative(String)
,getAdditionalStatesDerivatives()
-
getAdditionalDataValues
public DataDictionary getAdditionalDataValues()
Get an unmodifiable map of additional data.- Returns:
- unmodifiable map of additional data
- Since:
- 11.1
- See Also:
addAdditionalData(String, Object)
,hasAdditionalData(String)
,getAdditionalState(String)
-
getAdditionalStatesDerivatives
public DoubleArrayDictionary getAdditionalStatesDerivatives()
Get an unmodifiable map of additional states derivatives.- Returns:
- unmodifiable map of additional states derivatives
- Since:
- 11.1
- See Also:
addAdditionalStateDerivative(String, double[])
,hasAdditionalStateDerivative(String)
,getAdditionalStateDerivative(String)
-
toTransform
public Transform toTransform()
Compute the transform from state defining frame to spacecraft frame.The spacecraft frame origin is at the point defined by the orbit (or absolute position-velocity-acceleration), and its orientation is defined by the attitude.
- Returns:
- transform from specified frame to current spacecraft frame
-
toStaticTransform
public StaticTransform toStaticTransform()
Compute the static transform from state defining frame to spacecraft frame.- Returns:
- static transform from specified frame to current spacecraft frame
- Since:
- 12.0
- See Also:
toTransform()
-
getPosition
public Vector3D getPosition()
Get the position in orbit definition frame.- Returns:
- position in orbit definition frame
- Since:
- 12.0
- See Also:
getPVCoordinates()
-
getPVCoordinates
public TimeStampedPVCoordinates getPVCoordinates()
Get theTimeStampedPVCoordinates
in orbit definition frame.Compute the position and velocity of the satellite. This method caches its results, and recompute them only when the method is called with a new value for mu. The result is provided as a reference to the internally cached
TimeStampedPVCoordinates
, so the caller is responsible to copy it in a separateTimeStampedPVCoordinates
if it needs to keep the value for a while.- Returns:
- pvCoordinates in orbit definition frame
-
getPosition
public Vector3D getPosition(Frame outputFrame)
Get the position in given output frame.- Parameters:
outputFrame
- frame in which position should be defined- Returns:
- position in given output frame
- Since:
- 12.0
- See Also:
getPVCoordinates(Frame)
-
getPVCoordinates
public TimeStampedPVCoordinates getPVCoordinates(Frame outputFrame)
Get theTimeStampedPVCoordinates
in given output frame.Compute the position and velocity of the satellite. This method caches its results, and recompute them only when the method is called with a new value for mu. The result is provided as a reference to the internally cached
TimeStampedPVCoordinates
, so the caller is responsible to copy it in a separateTimeStampedPVCoordinates
if it needs to keep the value for a while.- Parameters:
outputFrame
- frame in which coordinates should be defined- Returns:
- pvCoordinates in given output frame
-
getAttitude
public Attitude getAttitude()
Get the attitude.- Returns:
- the attitude.
-
getMass
public double getMass()
Gets the current mass.- Returns:
- the mass (kg)
-
-