Package org.orekit.propagation

Class FieldSpacecraftState<T extends CalculusFieldElement<T>>

java.lang.Object
org.orekit.propagation.FieldSpacecraftState<T>
Type Parameters:
T - type of the field elements
All Implemented Interfaces:
FieldTimeShiftable<FieldSpacecraftState<T>,T>, FieldTimeStamped<T>, TimeShiftable<FieldSpacecraftState<T>>
public class FieldSpacecraftState<T extends CalculusFieldElement<T>> extends Object implements FieldTimeStamped<T>, FieldTimeShiftable<FieldSpacecraftState<T>,T>
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 FieldOrbit, or a FieldAbsolutePVCoordinates if there is no definite central body, plus the current mass and attitude at the intrinsic FieldAbsoluteDate. Quantities 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 actual shift varies between FieldOrbit and FieldAbsolutePVCoordinates. 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 FieldSpacecraftState is guaranteed to be immutable.

Author:
Fabien Maussion, Véronique Pommier-Maurussane, Luc Maisonobe, Vincent Mouraux
See Also:

  • Constructor Details

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldOrbit<T> orbit)
      Build a spacecraft state from orbit only.

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

      Parameters:
      orbit - the orbit

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldOrbit<T> orbit, FieldAttitude<T> 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 orbit
      attitude - attitude
      Throws:
      IllegalArgumentException - if orbit and attitude dates or frames are not equal

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldOrbit<T> orbit, FieldAttitude<T> attitude, T mass, FieldDataDictionary<T> additional, FieldArrayDictionary<T> additionalDot) 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 derivative sare available)
      Throws:
      IllegalArgumentException - if orbit and attitude dates or frames are not equal
      Since:
      11.1

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldOrbit<T> orbit, FieldAttitude<T> attitude, T mass, T massRate, FieldDataDictionary<T> additional, FieldArrayDictionary<T> additionalDot) throws IllegalArgumentException
      Build a spacecraft state from orbit, attitude, mass, additional states and derivatives.
      Parameters:
      orbit - the orbit
      attitude - attitude
      mass - the mass (kg)
      massRate - the mass rate (kg/s)
      additional - additional states (may be null if no additional states are available)
      additionalDot - additional states derivatives(may be null if no additional states derivative sare available)
      Throws:
      IllegalArgumentException - if orbit and attitude dates or frames are not equal
      Since:
      14.0

    • FieldSpacecraftState

      public FieldSpacecraftState(Field<T> field, SpacecraftState state)
      Convert a FieldSpacecraftState.
      Parameters:
      field - field to which the elements belong
      state - state to convert

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldAbsolutePVCoordinates<T> absPva)
      Build a spacecraft state from absolute coordinates only.

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

      Parameters:
      absPva - position-velocity-acceleration

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldAbsolutePVCoordinates<T> absPva, FieldAttitude<T> attitude) throws IllegalArgumentException
      Build a spacecraft state from absolute coordinates and attitude. Kept for performance.

      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

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldAbsolutePVCoordinates<T> absPva, FieldAttitude<T> attitude, T mass, FieldDataDictionary<T> additional, FieldArrayDictionary<T> additionalDot) throws IllegalArgumentException
      Build a spacecraft state from absolute coordinates, attitude and mass.
      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 derivatives are available)
      Throws:
      IllegalArgumentException - if orbit and attitude dates or frames are not equal
      Since:
      11.1

    • FieldSpacecraftState

      public FieldSpacecraftState(FieldAbsolutePVCoordinates<T> absPva, FieldAttitude<T> attitude, T mass, T massRate, FieldDataDictionary<T> additional, FieldArrayDictionary<T> additionalDot) throws IllegalArgumentException
      Build a spacecraft state from absolute coordinates, attitude, mass and mass rate.
      Parameters:
      absPva - position-velocity-acceleration
      attitude - attitude
      mass - the mass (kg)
      massRate - mass rate (kg/s)
      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:
      14.0

  • Method Details

    • withMass

      public FieldSpacecraftState<T> withMass(T newMass)
      Create a new instance with input mass.
      Parameters:
      newMass - mass
      Returns:
      new state
      Since:
      13.0

    • withMassRate

      public FieldSpacecraftState<T> withMassRate(T newMassRate)
      Create a new instance with input mass.
      Parameters:
      newMassRate - mass rate
      Returns:
      new state
      Since:
      14.0

    • withAttitude

      public FieldSpacecraftState<T> withAttitude(FieldAttitude<T> newAttitude)
      Create a new instance with input attitude.
      Parameters:
      newAttitude - attitude
      Returns:
      new state
      Since:
      13.0

    • withAdditionalData

      public FieldSpacecraftState<T> withAdditionalData(FieldDataDictionary<T> newAdditional)
      Create a new instance with input additional data.
      Parameters:
      newAdditional - data
      Returns:
      new state
      Since:
      13.0

    • withAdditionalStatesDerivatives

      public FieldSpacecraftState<T> withAdditionalStatesDerivatives(FieldArrayDictionary<T> newAdditionalDot)
      Create a new instance with input additional data.
      Parameters:
      newAdditionalDot - additional derivatives
      Returns:
      new state
      Since:
      13.0

    • addAdditionalData

      public final FieldSpacecraftState<T> 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 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 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
      See Also:

    • addAdditionalStateDerivative

      @SafeVarargs public final FieldSpacecraftState<T> addAdditionalStateDerivative(String name, T... value)
      Add an additional state derivative. FieldSpacecraftState 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
      value - value of the additional state derivative
      Returns:
      a new instance, with the additional state derivative added
      See Also:

    • isOrbitDefined

      public boolean isOrbitDefined()
      Check if the state contains an orbit part.

      A state contains either an absolute position-velocity-acceleration or an orbit.

      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 case getAbsPVA() will not throw an exception)

    • shiftedBy

      public FieldSpacecraftState<T> shiftedBy(double dt)
      Get a time-shifted state.

      The state can be slightly shifted to close dates. This shift is based on a simple Keplerian model for orbit and Taylor series for absolute position-velocity. A linear extrapolation for attitude is used, taking the spin rate into account. The mass is changed linearly, as well as additional states if their derivatives are available. It 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<T extends CalculusFieldElement<T>>
      Parameters:
      dt - time shift in seconds
      Returns:
      a new state, shifted with respect to the instance (which is immutable)

    • shiftedBy

      public FieldSpacecraftState<T> shiftedBy(T dt)
      Get a time-shifted state.

      The state can be slightly shifted to close dates. This shift is based on a simple Keplerian model for orbit and Taylor series for absolute position-velocity. A linear extrapolation for attitude is used, taking the spin rate into account. The mass is changed linearly, as well as additional states if their derivatives are available. It 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 FieldTimeShiftable<FieldSpacecraftState<T extends CalculusFieldElement<T>>,T extends CalculusFieldElement<T>>
      Parameters:
      dt - time shift in seconds
      Returns:
      a new state, shifted with respect to the instance (which is immutable)

    • getAbsPVA

      public FieldAbsolutePVCoordinates<T> getAbsPVA() throws OrekitIllegalStateException
      Get the absolute position-velocity-acceleration.

      A state contains either an absolute position-velocity-acceleration or an orbit. Which one is present can be checked using isOrbitDefined().

      Returns:
      absolute position-velocity-acceleration
      Throws:
      OrekitIllegalStateException - if position-velocity-acceleration is null, which mean the state rather contains an FieldOrbit
      See Also:

    • getOrbit

      public FieldOrbit<T> getOrbit() throws OrekitIllegalStateException
      Get the current orbit.

      A state contains either an absolute position-velocity-acceleration or an orbit. Which one is present can be checked using isOrbitDefined().

      Returns:
      the orbit
      Throws:
      OrekitIllegalStateException - if orbit is null, which means the state rather contains an absolute position-velocity-acceleration
      See Also:

    • getDate

      public FieldAbsoluteDate<T> getDate()
      Get the date.
      Specified by:
      getDate in interface FieldTimeStamped<T extends CalculusFieldElement<T>>
      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:

    • 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
      See Also:

    • ensureCompatibleAdditionalStates

      public void ensureCompatibleAdditionalStates(FieldSpacecraftState<T> state) throws MathIllegalArgumentException
      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:
      MathIllegalArgumentException - if an additional state does not have the same dimension in both states

    • getAdditionalState

      public T[] getAdditionalState(String name)
      Get an additional state.
      Parameters:
      name - name of the additional state
      Returns:
      value of the additional state
      See Also:

    • 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:

    • getAdditionalStateDerivative

      public T[] 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:

    • getAdditionalDataValues

      public FieldDataDictionary<T> getAdditionalDataValues()
      Get an unmodifiable map of additional states.
      Returns:
      unmodifiable map of additional states
      Since:
      11.1
      See Also:

    • getAdditionalStatesDerivatives

      public FieldArrayDictionary<T> getAdditionalStatesDerivatives()
      Get an unmodifiable map of additional states derivatives.
      Returns:
      unmodifiable map of additional states derivatives
      Since:
      11.1
      See Also:

    • toTransform

      public FieldTransform<T> toTransform()
      Compute the transform from state defining frame to spacecraft frame.

      The spacecraft frame origin is at the point defined by the orbit, and its orientation is defined by the attitude.

      Returns:
      transform from specified frame to current spacecraft frame

    • toStaticTransform

      public FieldStaticTransform<T> 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:

    • getPosition

      public FieldVector3D<T> getPosition()
      Get the position in state definition frame.
      Returns:
      position in state definition frame
      Since:
      12.0

    • getVelocity

      public FieldVector3D<T> getVelocity()
      Get the velocity in state definition frame.
      Returns:
      velocity in state definition frame
      Since:
      13.1

    • getPVCoordinates

      public TimeStampedFieldPVCoordinates<T> getPVCoordinates()
      Get the TimeStampedFieldPVCoordinates 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 TimeStampedFieldPVCoordinates, so the caller is responsible to copy it in a separate TimeStampedFieldPVCoordinates if it needs to keep the value for a while.

      Returns:
      pvCoordinates in orbit definition frame

    • getPosition

      public FieldVector3D<T> 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

      public TimeStampedFieldPVCoordinates<T> getPVCoordinates(Frame outputFrame)
      Get the TimeStampedFieldPVCoordinates 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 TimeStampedFieldPVCoordinates, so the caller is responsible to copy it in a separate TimeStampedFieldPVCoordinates 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 FieldAttitude<T> getAttitude()
      Get the attitude.
      Returns:
      the attitude.

    • getMass

      public T getMass()
      Gets the current mass.
      Returns:
      the mass (kg)

    • getMassRate

      public T getMassRate()
      Gets the current mass rate.
      Returns:
      the mass (kg/S)
      Since:
      14.0

    • toSpacecraftState

      public SpacecraftState toSpacecraftState()
      To convert a FieldSpacecraftState instance into a SpacecraftState instance.
      Returns:
      SpacecraftState instance with the same properties

    • toString

      public String toString()
      Overrides:
      toString in class Object