Class 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 an AbsolutePVCoordinates if there is no definite central body, plus the current mass and attitude at the intrinsic AbsoluteDate. 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 and AbsolutePVCoordinates. 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
    • 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 orbit
        attitude - 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 withXXX
        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

        @Deprecated
        public SpacecraftState​(Orbit orbit,
                               Attitude attitude,
                               double mass)
                        throws IllegalArgumentException
        Deprecated.
        since 13.0, use withXXX
        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,
                               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 orbit
        attitude - attitude
        mass - 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-acceleration
        attitude - 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 withXXX
        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

        @Deprecated
        public SpacecraftState​(AbsolutePVCoordinates absPva,
                               Attitude attitude,
                               double mass)
                        throws IllegalArgumentException
        Deprecated.
        since 13.0, use withXXX
        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,
                               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-acceleration
        attitude - attitude
        mass - 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 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 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
      • 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
        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
        Since:
        13.0
      • getFrame

        public Frame getFrame()
        Get the defining frame.
        Returns:
        the frame in which state is defined
      • 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
      • 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 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
        See Also:
        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 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)