Package org.orekit.propagation

Class FieldSpacecraftState<T extends CalculusFieldElement<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:
    NumericalPropagator, SpacecraftState

    • Constructor Detail

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

        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,
                            T mass)
        Create a new instance from orbit and mass.

        FieldAttitude law is set to an unspecified default attitude.

        Parameters:
        orbit - the orbit
        mass - the mass (kg)

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldOrbit<T> orbit,
                            FieldArrayDictionary<T> additional)
        Build a spacecraft state from orbit and additional states.

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

        Parameters:
        orbit - the orbit
        additional - additional states
        Since:
        11.1

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldOrbit<T> orbit,
                            FieldAttitude<T> attitude,
                            FieldArrayDictionary<T> additional)
                     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

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldOrbit<T> orbit,
                            T mass,
                            FieldArrayDictionary<T> additional)
        Create a new instance from orbit, mass and additional states.

        FieldAttitude law is set to an unspecified default attitude.

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

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldOrbit<T> orbit,
                            FieldAttitude<T> attitude,
                            T mass,
                            FieldArrayDictionary<T> additional)
        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)
        Since:
        11.1

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldOrbit<T> orbit,
                            FieldAttitude<T> attitude,
                            T mass,
                            FieldArrayDictionary<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​(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 orbit only.

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

        Parameters:
        absPva - position-velocity-acceleration

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldAbsolutePVCoordinates<T> absPva,
                            T mass)
        Create a new instance from orbit and mass.

        Attitude law is set to an unspecified default attitude.

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

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldAbsolutePVCoordinates<T> absPva,
                            FieldArrayDictionary<T> additional)
        Build a spacecraft state from orbit only.

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

        Parameters:
        absPva - position-velocity-acceleration
        additional - additional states
        Since:
        11.1

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldAbsolutePVCoordinates<T> absPva,
                            T mass,
                            FieldArrayDictionary<T> additional)
        Create a new instance from orbit and mass.

        Attitude law is set to an unspecified default attitude.

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

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldAbsolutePVCoordinates<T> absPva,
                            FieldAttitude<T> attitude,
                            T mass,
                            FieldArrayDictionary<T> additional)
        Build a spacecraft state from orbit, 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)
        Since:
        11.1

      • FieldSpacecraftState

        public FieldSpacecraftState​(FieldAbsolutePVCoordinates<T> absPva,
                            FieldAttitude<T> attitude,
                            T mass,
                            FieldArrayDictionary<T> additional,
                            FieldArrayDictionary<T> additionalDot)
                     throws IllegalArgumentException
        Build a spacecraft state from orbit, 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

    • Method Detail

      • addAdditionalState

        @SafeVarargs
public final FieldSpacecraftState<T> addAdditionalState​(String name,
                                                        T... value)
        Add an additional state.

        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
        value - value of the additional state
        Returns:
        a new instance, with the additional state added
        See Also:
        hasAdditionalState(String), getAdditionalState(String), getAdditionalStatesValues()

      • 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:
        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 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, a linear extrapolation for attitude taking the spin rate into account and neither mass nor additional states changes. 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) except for the mass which stay unchanged

      • 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, a linear extrapolation for attitude taking the spin rate into account and neither mass nor additional states changes. 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) except for the mass which stay unchanged

      • getFrame

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

      • 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

      • 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:
        toTransform()

      • getMu

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

      • getKeplerianPeriod

        public T 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 contains an absolute position-velocity-acceleration rather than an orbit

      • getKeplerianMeanMotion

        public T 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 contains an absolute position-velocity-acceleration rather than an orbit

      • getA

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

      • getEquinoctialEx

        public T 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 contains an absolute position-velocity-acceleration rather than an orbit
        See Also:
        getE()

      • getEquinoctialEy

        public T 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 contains an absolute position-velocity-acceleration rather than an orbit
        See Also:
        getE()

      • getHx

        public T 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 contains an absolute position-velocity-acceleration rather than an orbit
        See Also:
        getI()

      • getHy

        public T 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 contains an absolute position-velocity-acceleration rather than an orbit
        See Also:
        getI()

      • getLv

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

      • getLE

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

      • getLM

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

      • getE

        public T getE()
        Get the eccentricity.
        Returns:
        eccentricity, or {code Double.NaN} if the state contains an absolute position-velocity-acceleration rather than an orbit
        See Also:
        getEquinoctialEx(), getEquinoctialEy()

      • getI

        public T getI()
        Get the inclination.
        Returns:
        inclination (rad)
        See Also:
        getHx(), getHy()

      • getPosition

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

      • 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(Frame)

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

      • toSpacecraftState

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