org.orekit.propagation

## Class SpacecraftState

• All Implemented Interfaces:
Serializable, TimeInterpolable<SpacecraftState>, TimeShiftable<SpacecraftState>, TimeStamped

public class SpacecraftState
extends Object
implements TimeStamped, TimeShiftable<SpacecraftState>, TimeInterpolable<SpacecraftState>, Serializable
This class is the representation of a complete state holding orbit, attitude and mass information at a given date.

It contains an orbital state at a current AbsoluteDate both handled by an Orbit, plus the current mass and attitude. Orbit and state are guaranteed to be consistent in terms of date and reference frame. The spacecraft state may also contain additional states, which are simply named double arrays which can hold any user-defined data.

The state can be slightly shifted to close dates. This shift is based on a simple Keplerian model for orbit, a linear extrapolation for attitude 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
NumericalPropagator, Serialized Form
• ### Constructor Summary

Constructors
Constructor and Description
SpacecraftState(AbsolutePVCoordinates absPva)
Build a spacecraft state from position-velocity-acceleration only.
SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude)
Build a spacecraft state from position-velocity-acceleration and attitude.
SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass)
Build a spacecraft state from position-velocity-acceleration, attitude and mass.
SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, DoubleArrayDictionary additional)
Build a spacecraft state from position-velocity-acceleration, attitude and additional states.
SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass, DoubleArrayDictionary additional)
Build a spacecraft state from position-velocity-acceleration, attitude, mass and additional states.
SpacecraftState(AbsolutePVCoordinates absPva, Attitude attitude, double mass, DoubleArrayDictionary additional, DoubleArrayDictionary additionalDot)
Build a spacecraft state from position-velocity-acceleration, attitude, mass and additional states and derivatives.
SpacecraftState(AbsolutePVCoordinates absPva, double mass)
Create a new instance from position-velocity-acceleration and mass.
SpacecraftState(AbsolutePVCoordinates absPva, DoubleArrayDictionary additional)
Build a spacecraft state from position-velocity-acceleration and additional states.
SpacecraftState(AbsolutePVCoordinates absPva, double mass, DoubleArrayDictionary additional)
Create a new instance from position-velocity-acceleration, mass and additional states.
SpacecraftState(Orbit orbit)
Build a spacecraft state from orbit only.
SpacecraftState(Orbit orbit, Attitude attitude)
Build a spacecraft state from orbit and attitude.
SpacecraftState(Orbit orbit, Attitude attitude, double mass)
Build a spacecraft state from orbit, attitude and mass.
SpacecraftState(Orbit orbit, Attitude attitude, DoubleArrayDictionary additional)
Build a spacecraft state from orbit, attitude and additional states.
SpacecraftState(Orbit orbit, Attitude attitude, double mass, DoubleArrayDictionary additional)
Build a spacecraft state from orbit, attitude, mass and additional states.
SpacecraftState(Orbit orbit, Attitude attitude, double mass, DoubleArrayDictionary additional, DoubleArrayDictionary additionalDot)
Build a spacecraft state from orbit, attitude, mass, additional states and derivatives.
SpacecraftState(Orbit orbit, double mass)
Create a new instance from orbit and mass.
SpacecraftState(Orbit orbit, DoubleArrayDictionary additional)
Build a spacecraft state from orbit and additional states.
SpacecraftState(Orbit orbit, double mass, DoubleArrayDictionary additional)
Create a new instance from orbit, mass and additional states.
• ### Method Summary

All Methods
Modifier and Type Method and Description
SpacecraftState addAdditionalState(String name, double... value)
SpacecraftState addAdditionalStateDerivative(String name, double... value)
void ensureCompatibleAdditionalStates(SpacecraftState state)
Check if two instances have the same set of additional states available.
double getA()
Get the semi-major axis.
AbsolutePVCoordinates getAbsPVA()
Get the absolute position-velocity-acceleration.
double[] getAdditionalState(String name)
double[] getAdditionalStateDerivative(String name)
DoubleArrayDictionary getAdditionalStatesDerivatives()
Get an unmodifiable map of additional states derivatives.
DoubleArrayDictionary getAdditionalStatesValues()
Get an unmodifiable map of additional states.
Attitude getAttitude()
Get the attitude.
AbsoluteDate getDate()
Get the date.
double getE()
Get the eccentricity.
double getEquinoctialEx()
Get the first component of the eccentricity vector (as per equinoctial parameters).
double getEquinoctialEy()
Get the second component of the eccentricity vector (as per equinoctial parameters).
Frame getFrame()
Get the defining frame.
double getHx()
Get the first component of the inclination vector (as per equinoctial parameters).
double getHy()
Get the second component of the inclination vector (as per equinoctial parameters).
double getI()
Get the inclination.
double getKeplerianMeanMotion()
Get the Keplerian mean motion.
double getKeplerianPeriod()
Get the Keplerian period.
double getLE()
Get the eccentric latitude argument (as per equinoctial parameters).
double getLM()
Get the mean longitude argument (as per equinoctial parameters).
double getLv()
Get the true latitude argument (as per equinoctial parameters).
double getMass()
Gets the current mass.
double getMu()
Get the central attraction coefficient.
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 the TimeStampedPVCoordinates in orbit definition frame.
TimeStampedPVCoordinates getPVCoordinates(Frame outputFrame)
Get the TimeStampedPVCoordinates in given output frame.
boolean hasAdditionalState(String name)
Check if an additional state is available.
boolean hasAdditionalStateDerivative(String name)
Check if an additional state derivative is available.
SpacecraftState interpolate(AbsoluteDate date, Stream<SpacecraftState> sample)
Get an interpolated instance.
boolean isOrbitDefined()
Check if the state contains an orbit part.
SpacecraftState shiftedBy(double dt)
Get a time-shifted state.
String toString()
Transform toTransform()
Compute the transform from state defining frame to spacecraft frame.
• ### Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
• ### Methods inherited from interface org.orekit.time.TimeInterpolable

interpolate
• ### 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.

Mass is set to an unspecified non-null arbitrary value.

Parameters:
orbit - the orbit
attitude - attitude
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
double mass)
Create a new instance from orbit and mass.

Attitude law is set to an unspecified default attitude.

Parameters:
orbit - the orbit
mass - the mass (kg)
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
Attitude attitude,
double mass)
throws IllegalArgumentException
Build a spacecraft state from orbit, attitude and mass.
Parameters:
orbit - the orbit
attitude - attitude
mass - the mass (kg)
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
DoubleArrayDictionary additional)
Build a spacecraft state from orbit and additional states.

Attitude and mass are set to unspecified non-null arbitrary values.

Parameters:
orbit - the orbit
additional - additional states
Since:
11.1
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
Attitude attitude,
throws IllegalArgumentException
Build a spacecraft state from orbit, attitude and additional states.

Mass is set to an unspecified non-null arbitrary value.

Parameters:
orbit - the orbit
attitude - attitude
additional - additional states
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
Since:
11.1
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
double mass,
DoubleArrayDictionary additional)
Create a new instance from orbit, mass and additional states.

Attitude law is set to an unspecified default attitude.

Parameters:
orbit - the orbit
mass - the mass (kg)
additional - additional states
Since:
11.1
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
Attitude attitude,
double mass,
throws IllegalArgumentException
Build a spacecraft state from orbit, attitude, mass and additional states.
Parameters:
orbit - the orbit
attitude - attitude
mass - the mass (kg)
additional - additional states (may be null if no additional states are available)
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
Since:
11.1
• #### SpacecraftState

public SpacecraftState(Orbit orbit,
Attitude attitude,
double mass,
throws IllegalArgumentException
Build a spacecraft state from orbit, attitude, mass, additional states and derivatives.
Parameters:
orbit - the orbit
attitude - attitude
mass - the mass (kg)
additional - additional states (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:
11.1
• #### 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.

Mass is set to an unspecified non-null arbitrary value.

Parameters:
absPva - position-velocity-acceleration
attitude - attitude
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
double mass)
Create a new instance from position-velocity-acceleration and mass.

Attitude law is set to an unspecified default attitude.

Parameters:
absPva - position-velocity-acceleration
mass - the mass (kg)
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
Attitude attitude,
double mass)
throws IllegalArgumentException
Build a spacecraft state from position-velocity-acceleration, attitude and mass.
Parameters:
absPva - position-velocity-acceleration
attitude - attitude
mass - the mass (kg)
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
DoubleArrayDictionary additional)
Build a spacecraft state from position-velocity-acceleration and additional states.

Attitude and mass are set to unspecified non-null arbitrary values.

Parameters:
absPva - position-velocity-acceleration
additional - additional states
Since:
11.1
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
Attitude attitude,
throws IllegalArgumentException
Build a spacecraft state from position-velocity-acceleration, attitude and additional states.

Mass is set to an unspecified non-null arbitrary value.

Parameters:
absPva - position-velocity-acceleration
attitude - attitude
additional - additional states
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
Since:
11.1
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
double mass,
DoubleArrayDictionary additional)
Create a new instance from position-velocity-acceleration, mass and additional states.

Attitude law is set to an unspecified default attitude.

Parameters:
absPva - position-velocity-acceleration
mass - the mass (kg)
additional - additional states
Since:
11.1
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
Attitude attitude,
double mass,
throws IllegalArgumentException
Build a spacecraft state from position-velocity-acceleration, attitude, mass and additional states.
Parameters:
absPva - position-velocity-acceleration
attitude - attitude
mass - the mass (kg)
additional - additional states (may be null if no additional states are available)
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
Since:
11.1
• #### SpacecraftState

public SpacecraftState(AbsolutePVCoordinates absPva,
Attitude attitude,
double mass,
throws IllegalArgumentException
Build a spacecraft state from position-velocity-acceleration, attitude, mass and additional states and derivatives.
Parameters:
absPva - position-velocity-acceleration
attitude - attitude
mass - the mass (kg)
additional - additional states (may be null if no additional states are available)
additionalDot - additional states derivatives(may be null if no additional states derivativesare available)
Throws:
IllegalArgumentException - if orbit and attitude dates or frames are not equal
Since:
11.1
• ### Method Detail

public SpacecraftState addAdditionalState(String name,
double... value)

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 state 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 state (names containing "orekit" with any case are reserved for the library internal use)
value - value of the additional state
Returns:
hasAdditionalState(String), getAdditionalState(String), getAdditionalStatesValues()

public SpacecraftState addAdditionalStateDerivative(String name,
double... value)

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:
Since:
11.1
hasAdditionalStateDerivative(String), getAdditionalStateDerivative(String), getAdditionalStatesDerivatives()
• #### 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
60016011067
90031413307
Specified by:
shiftedBy in interface TimeShiftable<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
• #### interpolate

public SpacecraftState interpolate(AbsoluteDate date,
Stream<SpacecraftState> sample)
Get an interpolated instance.

Note that the state of the current instance may not be used in the interpolation process, only its type and non interpolable fields are used (for example central attraction coefficient or frame when interpolating orbits). The interpolable fields taken into account are taken only from the states of the sample points. So if the state of the instance must be used, the instance should be included in the sample points.

Note that this method is designed for small samples only (say up to about 10-20 points) so it can be implemented using polynomial interpolation (typically Hermite interpolation). Using too much points may induce Runge's phenomenon and numerical problems (including NaN appearing).

The additional states that are interpolated are the ones already present in the instance. The sample instances must therefore have at least the same additional states has the instance. They may have more additional states, but the extra ones will be ignored.

The instance and all the sample instances must be based on similar trajectory data, i.e. they must either all be based on orbits or all be based on absolute position-velocity-acceleration. Any inconsistency will trigger an OrekitIllegalStateException.

As this implementation of interpolation is polynomial, it should be used only with small samples (about 10-20 points) in order to avoid Runge's phenomenon and numerical problems (including NaN appearing).

Specified by:
interpolate in interface TimeInterpolable<SpacecraftState>
Parameters:
date - interpolation date
sample - sample points on which interpolation should be done
Returns:
a new instance, interpolated at specified date
Throws:
OrekitIllegalStateException - if some instances are not based on similar trajectory data
• #### getDate

public AbsoluteDate getDate()
Get the date.
Specified by:
getDate in interface TimeStamped
Returns:
date
• #### getFrame

public Frame getFrame()
Get the defining frame.
Returns:
the frame in which state is defined

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
• #### 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
• #### getMu

public double getMu()
Get the central attraction coefficient.
Returns:
mu central attraction coefficient (m^3/s^2), or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
• #### getKeplerianPeriod

public double getKeplerianPeriod()
Get the Keplerian period.

The Keplerian period is computed directly from semi major axis and central acceleration constant.

Returns:
keplerian period in seconds, or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
• #### getKeplerianMeanMotion

public double getKeplerianMeanMotion()
Get the Keplerian mean motion.

The Keplerian mean motion is computed directly from semi major axis and central acceleration constant.

Returns:
keplerian mean motion in radians per second, or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
• #### getA

public double getA()
Get the semi-major axis.
Returns:
semi-major axis (m), or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
• #### getEquinoctialEx

public double getEquinoctialEx()
Get the first component of the eccentricity vector (as per equinoctial parameters).
Returns:
e cos(ω + Ω), first component of eccentricity vector, or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getE()
• #### getEquinoctialEy

public double getEquinoctialEy()
Get the second component of the eccentricity vector (as per equinoctial parameters).
Returns:
e sin(ω + Ω), second component of the eccentricity vector, or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getE()
• #### getHx

public double getHx()
Get the first component of the inclination vector (as per equinoctial parameters).
Returns:
tan(i/2) cos(Ω), first component of the inclination vector, or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getI()
• #### getHy

public double getHy()
Get the second component of the inclination vector (as per equinoctial parameters).
Returns:
tan(i/2) sin(Ω), second component of the inclination vector, or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getI()
• #### getLv

public double getLv()
Get the true latitude argument (as per equinoctial parameters).
Returns:
v + ω + Ω true longitude argument (rad), or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getLE(), getLM()
• #### getLE

public double getLE()
Get the eccentric latitude argument (as per equinoctial parameters).
Returns:
E + ω + Ω eccentric longitude argument (rad), or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getLv(), getLM()
• #### getLM

public double getLM()
Get the mean longitude argument (as per equinoctial parameters).
Returns:
M + ω + Ω mean latitude argument (rad), or {code Double.NaN} if the state is contains an absolute position-velocity-acceleration rather than an orbit
getLv(), getLE()
• #### getPosition

public Vector3D getPosition()
Get the position in orbit definition frame.
Returns:
position in orbit definition frame
Since:
12.0
getPVCoordinates()
• #### getPVCoordinates

public TimeStampedPVCoordinates getPVCoordinates()
Get the TimeStampedPVCoordinates 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 separate TimeStampedPVCoordinates 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
getPVCoordinates(Frame)
• #### getPVCoordinates

public TimeStampedPVCoordinates getPVCoordinates(Frame outputFrame)
Get the TimeStampedPVCoordinates 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 separate TimeStampedPVCoordinates if it needs to keep the value for a while.

Parameters:
outputFrame - frame in which coordinates should be defined
Returns:
pvCoordinates in orbit definition frame
• #### getAttitude

public Attitude getAttitude()
Get the attitude.
Returns:
the attitude.
• #### getMass

public double getMass()
Gets the current mass.
Returns:
the mass (kg)
• #### toString

public String toString()
Overrides:
toString in class Object