fr.cnes.sirius.patrius.covariance

Class MultiOrbitalCovariance

java.lang.Object

fr.cnes.sirius.patrius.covariance.AbstractOrbitalCovariance<MultiOrbitalCovariance>

fr.cnes.sirius.patrius.covariance.MultiOrbitalCovariance

All Implemented Interfaces:

TimeStamped, Serializable

public class MultiOrbitalCovariance
extends AbstractOrbitalCovariance<MultiOrbitalCovariance>

Orbital covariance associated with multiple orbits.

This class associates a Covariance instance with multiple orbits, their common date being the date of definition of the orbital covariance. The frame, orbit type (Cartesian, Keplerian, etc) and position angle type (mean, true, eccentric) in which the Covariance is expressed are specified at construction.

The covariance matrix must be at least N by N, where N is the number of orbits multiplied by the number of orbital parameters (SpacecraftState.ORBIT_DIMENSION).
Nevertheless, it can have a bigger size to take into account additional parameters. The latter can be of two different nature:

• attached to a specific orbit (drag coefficient for example)
• without associated orbit (environment parameter for example)

The parameters must be ordered according to the following manner: for each orbit, first the orbital parameters (ordered acording to their index) then the additional parameters specific to the orbit. The additional parameters that are not attached to any orbit must be placed at the end.

The parameter descriptors of orbital parameters must be associated to an orbital coordinate descriptor, and these descriptors must be mapped to a valid OrbitalCoordinate (one with the expected orbit type and state vector index).

Author:

Hugo Veuillez (CNES), Pierre Seimandi (GMV)

See Also:

Serialized Form

Field Summary

Fields inherited from class fr.cnes.sirius.patrius.covariance.AbstractOrbitalCovariance

ORBIT_DIMENSION, ORBITAL_COORDINATE_DESCRIPTOR

Constructor Summary

Constructors

Constructor and Description
MultiOrbitalCovariance(Covariance covariance, Collection<Orbit> orbits, int[] nbAdditionalParametersIn, Frame frame, OrbitType orbitType, PositionAngle positionAngle) Creates a new instance that associates a covariance matrix with multiple orbits, the covariance being defined in the specified frame, orbit type and position angle type.
MultiOrbitalCovariance(SymmetricPositiveMatrix covarianceMatrix, Collection<Orbit> orbits, int[] nbAdditionalParametersIn, Frame frame, OrbitType orbitType, PositionAngle positionAngle) Creates a new instance that associates a covariance matrix with multiple orbits, the covariance being defined in the specified frame, orbit type and position angle type.

Method Summary

Modifier and Type	Method and Description
MultiOrbitalCovariance	copy() Gets a copy of this orbital covariance.
boolean	equals(Object object)
AbsoluteDate	getDate() Get the date.
Orbit	getOrbit(int index) Gets a specific orbit from the list of associated orbits.
OrbitalCovariance	getOrbitalCovariance(int index) Extracts the orbital covariance of the selected orbit. By default, does not include the additional parameters that are not attached to any orbit.
OrbitalCovariance	getOrbitalCovariance(int index, boolean includeNonOrbitalAdditionalParameters) Extracts the orbital covariance of the selected orbit.
List<Orbit>	getOrbits() Gets the list of associated orbits.
Covariance	getRelativeCovariance(int index1, int index2) Computes the relative covariance between two orbits.
ArrayRowSymmetricPositiveMatrix	getRelativeCovarianceMatrix(int index1, int index2) Computes the relative covariance matrix between two orbits.
int	hashCode()
MultiOrbitalCovariance	shiftedBy(double dt) Shifts the orbital covariance in time by a given duration.
MultiOrbitalCovariance	transformTo(Frame destFrame, OrbitType destOrbitType, PositionAngle destPositionAngle) Transforms this orbital covariance to the specified frame, orbit type and position angle type.
MultiOrbitalCovariance	transformTo(int index, LOFType lofType, boolean frozenLof) Transforms this orbital covariance to a local orbital frame centered on a given orbit.
MultiOrbitalCovariance	transformTo(Orbit referenceOrbit, LOFType lofType, boolean frozenLof) Transforms this orbital covariance to a local orbital frame centered on a given orbit.

Methods inherited from class fr.cnes.sirius.patrius.covariance.AbstractOrbitalCovariance

checkCovarianceMatrixDimension, checkCovarianceMatrixDimension, checkOrbit, checkParameterDescriptors, checkParameterDescriptors, convertParameterDescriptors, getCovariance, getCovarianceMatrix, getFrame, getOrbitType, getParameterDescriptors, getPositionAngle, initParameterDescriptors, requireNonEmpty, requireNonNull, toString, toString, toString, toString, transformTo, transformTo, transformTo, transformTo, transformTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

MultiOrbitalCovariance

public MultiOrbitalCovariance(SymmetricPositiveMatrix covarianceMatrix,
                              Collection<Orbit> orbits,
                              int[] nbAdditionalParametersIn,
                              Frame frame,
                              OrbitType orbitType,
                              PositionAngle positionAngle)

Creates a new instance that associates a covariance matrix with multiple orbits, the covariance being defined in the specified frame, orbit type and position angle type.

The covariance matrix must be at least N by N, where N is the number of orbits multiplied by the number of orbital parameters. Each orbit is associated with K consecutive rows/columns, where the first six represent the uncertainty on the orbital parameters and the remaining ones represent the uncertainty on the additional parameters. The parameter descriptors of these first six rows/columns are automatically associated with an orbital coordinate descriptor, mapped to a valid OrbitalCoordinate.

Note that additional parameters that are not related to any orbit can be present at the end of the covariance matrix

Parameters:

covarianceMatrix - the covariance matrix

orbits - the orbits associated with the covariance

nbAdditionalParametersIn - the number of additional parameters for each orbit

frame - the frame of the covariance

orbitType - the orbit type of the covariance

positionAngle - the position angle type of the covariance

Throws:

IllegalArgumentException - if any of the provided arguments is null or if the orbits collection is null or empty or if all the orbits aren't defined at the same date

MultiOrbitalCovariance

public MultiOrbitalCovariance(Covariance covariance,
                              Collection<Orbit> orbits,
                              int[] nbAdditionalParametersIn,
                              Frame frame,
                              OrbitType orbitType,
                              PositionAngle positionAngle)

Creates a new instance that associates a covariance matrix with multiple orbits, the covariance being defined in the specified frame, orbit type and position angle type.

The covariance matrix must be at least N by N, where N is the number of orbits multiplied by the number of orbital parameters. Each orbit is associated with K consecutive rows/columns, where the first six represent the uncertainty on the orbital parameters and the remaining ones represent the uncertainty on the additional parameters. The parameter descriptors of these first six rows/columns must be associated to an orbital coordinate descriptor, and these descriptors must be mapped to a valid OrbitalCoordinate (one with the expected orbit type and state vector index).

Note that additional parameters that are not related to any orbit can be present at the end of the covariance matrix

Parameters:

covariance - the covariance matrix

orbits - the orbits associated with the covariance

nbAdditionalParametersIn - the number of additional parameters for each orbit

frame - the frame of the covariance

orbitType - the orbit type of the covariance

positionAngle - the position angle type of the covariance

Throws:

IllegalArgumentException - if any of the provided arguments is null or if the orbits collection is null or empty or if all the orbits aren't defined at the same date

Method Detail

getDate

public AbsoluteDate getDate()

Get the date.

Returns:

date attached to the object

getOrbits

public List<Orbit> getOrbits()

Gets the list of associated orbits.

Returns:

the list of associated orbits

getOrbit

public Orbit getOrbit(int index)

Gets a specific orbit from the list of associated orbits.

Parameters:

index - the index of the orbit to be retrieved

Returns:

the selected associated orbit

Throws:

IllegalArgumentException - if the provided index is invalid

getOrbitalCovariance

public OrbitalCovariance getOrbitalCovariance(int index)

Extracts the orbital covariance of the selected orbit.
By default, does not include the additional parameters that are not attached to any orbit.

Parameters:

index - the index of the selected orbit in the orbits list

Returns:

the orbital covariance of the selected orbit

Throws:

IllegalArgumentException - if the provided index is invalid

getOrbitalCovariance

public OrbitalCovariance getOrbitalCovariance(int index,
                                              boolean includeNonOrbitalAdditionalParameters)

Extracts the orbital covariance of the selected orbit.

Parameters:

index - the index of the selected orbit in the orbits list

includeNonOrbitalAdditionalParameters - include the additional parameters that are not attached to any orbit (if true)

Returns:

the orbital covariance of the selected orbit

Throws:

IllegalArgumentException - if the provided index is invalid

getRelativeCovariance

public Covariance getRelativeCovariance(int index1,
                                        int index2)

Computes the relative covariance between two orbits.

The relative covariance matrix is defined by:
C_rel = C_i + C_j -C_i,j -C_j,i
where C_i and C_j are the covariance submatrices related representing the uncertainty on the orbital parameters of the i^th and j^th orbits, and where C_i,j and C_j,i are the submatrices representing the correlations between the orbital parameters of the two orbits.

As an example, for three satellites the complete covariance matrix would be:
[C₁, C_1,2, C_1,3]
[C_2,1, C₂, C_2,3]
[C_3,1, C_3,2, C₃]

The parameter descriptors associated with the relative covariance matrix are built by intersecting the parameter descriptors describing the same orbital coordinate. This intersection only keeps the identical field descriptors and may result in an empty parameter descriptor if the orbital coordinate descriptors are mapped to different kind of orbital coordinates. Since Covariance instances do not allow empty parameter descriptors, an exception is thrown if that occurs.

Parameters:

index1 - the index of the first selected orbit in the list of associated orbits

index2 - the index of the second selected orbit in the list of associated orbits

Returns:

the relative covariance between the two selected orbits

getRelativeCovarianceMatrix

public ArrayRowSymmetricPositiveMatrix getRelativeCovarianceMatrix(int index1,
                                                                   int index2)

Computes the relative covariance matrix between two orbits.

The relative covariance matrix is defined by:
C_rel = C_i + C_j -C_i,j -C_j,i
where C_i and C_j are the covariance submatrices related representing the uncertainty on the orbital parameters of the i^th and j^th orbits, and where C_i,j and C_j,i are the submatrices representing the correlations between the orbital parameters of the two orbits.

As an example, for three satellites the complete covariance matrix would be:
[C₁, C_1,2, C_1,3]
[C_2,1, C₂, C_2,3]
[C_3,1, C_3,2, C₃]

Parameters:

index1 - the index of the first selected orbit in the list of associated orbits

index2 - the index of the second selected orbit in the list of associated orbits

Returns:

the relative covariance between the two selected orbits

shiftedBy

public MultiOrbitalCovariance shiftedBy(double dt)
                                 throws PatriusException

Shifts the orbital covariance in time by a given duration.

The shift of the orbital covariance is based on a simple Keplerian model. It is not intended as a replacement for proper covariance propagation, but it should be sufficient for small time shifts or coarse accuracy.

Parameters:

dt - the time shift

Returns:

the time-shifted orbital covariance

Throws:

PatriusException - if the Keplerian transition matrix cannot be computed

transformTo

public MultiOrbitalCovariance transformTo(Frame destFrame,
                                          OrbitType destOrbitType,
                                          PositionAngle destPositionAngle)
                                   throws PatriusException

Transforms this orbital covariance to the specified frame, orbit type and position angle type.

Important:
The use of non-Cartesian coordinates types may be incompatible with some frames (e.g. local orbital frames).

Specified by:

transformTo in class AbstractOrbitalCovariance<MultiOrbitalCovariance>

Parameters:

destFrame - the destination frame

destOrbitType - the destination orbit type

destPositionAngle - the destination position angle type

Returns:

the transformed orbital covariance

Throws:

PatriusException - if the orbital covariance cannot be transformed to the specified frame, orbit type and position angle type

transformTo

public MultiOrbitalCovariance transformTo(int index,
                                          LOFType lofType,
                                          boolean frozenLof)
                                   throws PatriusException

Transforms this orbital covariance to a local orbital frame centered on a given orbit.

Important:
The returned covariance is defined in Cartesian coordinates, in the specified LOFType. Note that the local orbital frame uses the reference orbit as its PVCoordinatesProvider, which relies on a simple Keplerian model for the propagation. The LOF built is therefore only valid locally, at the date of the reference orbit, unless it is frozen at this date (the LOF then becomes an inertial frame which can be used at other dates).

Parameters:

index - the index of the selected orbit in the list of associated orbits, which will be used to build the local orbital frame

lofType - the type of the local orbital frame

frozenLof - whether or not the local orbital frame built should be frozen at the date of the reference orbit

Returns:

the transformed orbital covariance

Throws:

PatriusException - if the orbital covariance cannot be transformed to the specified local orbital frame

transformTo

public MultiOrbitalCovariance transformTo(Orbit referenceOrbit,
                                          LOFType lofType,
                                          boolean frozenLof)
                                   throws PatriusException

Transforms this orbital covariance to a local orbital frame centered on a given orbit.

The reference orbit must be defined at the same date as the covariance.

Important:
The returned covariance is defined in Cartesian coordinates, in the specified LOFType. Note that the local orbital frame uses the reference orbit as its PVCoordinatesProvider, which relies on a simple Keplerian model for the propagation. The LOF built is therefore only valid locally, at the date of the reference orbit, unless it is frozen at this date (the LOF then becomes an inertial frame which can be used at other dates).

Parameters:

referenceOrbit - the orbit used to build the local orbital frame

lofType - the type of the local orbital frame

frozenLof - whether or not the local orbital frame built should be frozen at the date of the reference orbit

Returns:

the transformed orbital covariance

Throws:

PatriusException - if the orbital covariance cannot be transformed to the specified local orbital frame

copy

public MultiOrbitalCovariance copy()

Gets a copy of this orbital covariance.

This method performs a shallow copy of the associated covariance (shallow copy of the parameter descriptors list, deep copy of the covariance matrix) and a shallow copy of the list of orbits (which are immutable). The frame, orbit type and position angle type are all passed by reference since they are immutable.

Returns:

a copy of this orbital covariance

See Also:

Covariance.copy()

equals

public boolean equals(Object object)

Overrides:

equals in class AbstractOrbitalCovariance<MultiOrbitalCovariance>

hashCode

public int hashCode()

Overrides:

hashCode in class AbstractOrbitalCovariance<MultiOrbitalCovariance>