fr.cnes.sirius.patrius.forces

Class EmpiricalForce

java.lang.Object

fr.cnes.sirius.patrius.math.parameter.Parameterizable

fr.cnes.sirius.patrius.math.parameter.JacobiansParameterizable

fr.cnes.sirius.patrius.forces.EmpiricalForce

All Implemented Interfaces:

ForceModel, GradientModel, IJacobiansParameterizable, IParameterizable, Serializable

public class EmpiricalForce
extends JacobiansParameterizable
implements ForceModel, GradientModel

This class implements the empirical force. An empirical force is a "pseudo acceleration" with the same frequency of the spacecraft orbital frequency (or a multiple of this frequency). This class allows to model a bunch of empirical forces, such as Hill, Hill2 and bias.

Given an orbit and a local frame (usually a LOF frame), and three vectors A, B and C defined in this frame, the acceleration due to a generic empirical force is the following:
a_loc = Acos(nωt) + Bsin(nωt) + C,
where n is the harmonic factor and ω is the orbital period.

As ω is usually unknown, cos(nωt) and sin(nωt) are computed from the orbital position of the spacecraft:

• when the orbit is highly inclined, the orbital position can be computed from the position of the ascending node;
• when the orbit is heliosyncronous, the orbital position can be computed from the projection of the Sun in the orbital plane;

To avoid to be restricted to these two cases, the user is free to choose a vector S that is used to define a reference direction V (V = S x ω); this reference direction is used to compute cos(nωt) and sin(nωt):

• S =(0, 0, 1) when the reference direction V is the position of the ascending node;
• S = sun direction in the inertial frame when the orbit is heliosyncronous.

This vector S shall be expressed in the inertial frame associated to the SpacecraftState.

The implementation of this class enables the computation of partial derivatives with respect to the X, Y and Z-components of the A, B and C coefficients.

Since:

1.2

Version:

$Id$

Author:

Tiziana Sabatini

See Also:

Serialized Form

Concurrency :

not thread-safe

Concurrency comment :

attributes are mutable

Field Summary

Fields

Modifier and Type	Field and Description
static String	AX_COEFFICIENT X-component of the A coefficient.
static String	AY_COEFFICIENT Y-component of the A coefficient.
static String	AZ_COEFFICIENT Z-component of the A coefficient.
static String	BX_COEFFICIENT X-component of the B coefficient.
static String	BY_COEFFICIENT Y-component of the B coefficient.
static String	BZ_COEFFICIENT Z-component of the B coefficient.
static String	CX_COEFFICIENT X-component of the C coefficient.
static String	CY_COEFFICIENT Y-component of the C coefficient.
static String	CZ_COEFFICIENT Z-component of the C coefficient.

Constructor Summary

Constructors

Constructor and Description
EmpiricalForce(int harmonicFactor, Vector3D vectorS, IParamDiffFunction ax, IParamDiffFunction ay, IParamDiffFunction az, IParamDiffFunction bx, IParamDiffFunction by, IParamDiffFunction bz, IParamDiffFunction cx, IParamDiffFunction cy, IParamDiffFunction cz, Frame coeffsFrame) Simple constructor for an empiric force using parameterizable functions for A; B and C coef with a given frame.
EmpiricalForce(int harmonicFactor, Vector3D vectorS, IParamDiffFunction ax, IParamDiffFunction ay, IParamDiffFunction az, IParamDiffFunction bx, IParamDiffFunction by, IParamDiffFunction bz, IParamDiffFunction cx, IParamDiffFunction cy, IParamDiffFunction cz, LOFType coeffsFrameLOFType) Simple constructor for an empiric force using parameterizable functions for A; B and C coef with a given LOF frame.
EmpiricalForce(int harmonicFactor, Vector3D vectorS, Parameter ax, Parameter ay, Parameter az, Parameter bx, Parameter by, Parameter bz, Parameter cx, Parameter cy, Parameter cz, Frame coeffsFrame) Simple constructor for an empiric force using Parameter for A; B and C coef with a given frame.
EmpiricalForce(int harmonicFactor, Vector3D vectorS, Parameter ax, Parameter ay, Parameter az, Parameter bx, Parameter by, Parameter bz, Parameter cx, Parameter cy, Parameter cz, LOFType coeffsFrameLOFType) Simple constructor for an empiric force using Parameter for A; B and C coef with a given LOF frame.
EmpiricalForce(int harmonicFactor, Vector3D vectorS, Vector3D a, Vector3D b, Vector3D c, Frame coeffsFrame) Simple constructor for an empiric force, assigning a generic frame to the A, B, C coefficients frame.
EmpiricalForce(int harmonicFactor, Vector3D vectorS, Vector3D a, Vector3D b, Vector3D c, LOFType coeffsFrameLOFType) Simple constructor for an empiric force.

Method Summary

Modifier and Type	Method and Description
void	addContribution(SpacecraftState state, TimeDerivativesEquations adder) Compute the contribution of the force model to the perturbing acceleration.
void	addDAccDParam(SpacecraftState state, Parameter param, double[] dAccdParam) Compute acceleration derivatives with respect to additional parameters.
void	addDAccDState(SpacecraftState state, double[][] dAccdPos, double[][] dAccdVel) Compute acceleration derivatives with respect to state parameters.
void	checkData(AbsoluteDate start, AbsoluteDate end) This methods throws an exception if the user did not provide all the required data to perform model call on provided range [start; end].
Vector3D	computeAcceleration(PVCoordinates pv, LocalOrbitalFrame localFrameValidation, Vector3D vectorS, Frame frame, SpacecraftState state) Method to compute the acceleration.
Vector3D	computeAcceleration(SpacecraftState state) Compute the acceleration due to the force.
double[]	computeCosSin(PVCoordinates pv, Vector3D vectorS) Private method to compute the cos(nwt) and sin(nwt) values.
boolean	computeGradientPosition() This method returns true if the acceleration partial derivatives with respect to position have to be computed.
boolean	computeGradientVelocity() This method returns true if the acceleration partial derivatives with respect to velocity have to be computed.
IParamDiffFunction	getAx() Get the parametereziable function for the Ax coefficient.
IParamDiffFunction	getAy() Get the parametereziable function for the Ay coefficient.
IParamDiffFunction	getAz() Get the parametereziable function for the Az coefficient.
IParamDiffFunction	getBx() Get the parametereziable function for the Bx coefficient.
IParamDiffFunction	getBy() Get the parametereziable function for the By coefficient.
IParamDiffFunction	getBz() Get the parametereziable function for the Bz coefficient.
IParamDiffFunction	getCx() Get the parametereziable function for the Ax coefficient.
IParamDiffFunction	getCy() Get the parametereziable function for the Cy coefficient.
IParamDiffFunction	getCz() Get the parametereziable function for the Cz coefficient.
EventDetector[]	getEventsDetectors() Get the discrete events related to the model.
Frame	getLocalFrame()
Vector3D	getVectorS()

Methods inherited from class fr.cnes.sirius.patrius.math.parameter.JacobiansParameterizable

addJacobiansParameter, addJacobiansParameter, addJacobiansParameter, supportsJacobianParameter

Methods inherited from class fr.cnes.sirius.patrius.math.parameter.Parameterizable

addParameter, getParameters, supportsParameter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface fr.cnes.sirius.patrius.math.parameter.IParameterizable

getParameters, supportsParameter

Field Detail

AX_COEFFICIENT

public static final String AX_COEFFICIENT

X-component of the A coefficient.

See Also:

Constant Field Values

AY_COEFFICIENT

public static final String AY_COEFFICIENT

Y-component of the A coefficient.

See Also:

Constant Field Values

AZ_COEFFICIENT

public static final String AZ_COEFFICIENT

Z-component of the A coefficient.

See Also:

Constant Field Values

BX_COEFFICIENT

public static final String BX_COEFFICIENT

X-component of the B coefficient.

See Also:

Constant Field Values

BY_COEFFICIENT

public static final String BY_COEFFICIENT

Y-component of the B coefficient.

See Also:

Constant Field Values

BZ_COEFFICIENT

public static final String BZ_COEFFICIENT

Z-component of the B coefficient.

See Also:

Constant Field Values

CX_COEFFICIENT

public static final String CX_COEFFICIENT

X-component of the C coefficient.

See Also:

Constant Field Values

CY_COEFFICIENT

public static final String CY_COEFFICIENT

Y-component of the C coefficient.

See Also:

Constant Field Values

CZ_COEFFICIENT

public static final String CZ_COEFFICIENT

Z-component of the C coefficient.

See Also:

Constant Field Values

Constructor Detail

EmpiricalForce

public EmpiricalForce(int harmonicFactor,
                      Vector3D vectorS,
                      Vector3D a,
                      Vector3D b,
                      Vector3D c,
                      Frame coeffsFrame)

Simple constructor for an empiric force, assigning a generic frame to the A, B, C coefficients frame.
It sets the parameters used for the acceleration computation: a_loc = Acos(nωt) + Bsin(nωt) + C.
WARNING: If the frame of definition of vectors A,B and C is a local orbital frame (LOF), this constructor must NOT be used (acceleration computation would fail); The EmpiricalForce(int, Vector3D, Vector3D, Vector3D, Vector3D, LOFType) constructor should be used instead to avoid problems during propagation.

Parameters:

harmonicFactor - the harmonic factor n.

vectorS - the direction whose cross product with ω is used as a reference direction to compute the cos(nωt) and sin(nωt) terms.

a - the vector representing the A coefficient (expressed in the local frame).

b - the vector representing the B coefficient (expressed in the local frame).

c - the vector representing the C coefficient (expressed in the local frame).

coeffsFrame - the frame of definition of vectors A, B and C.

EmpiricalForce

public EmpiricalForce(int harmonicFactor,
                      Vector3D vectorS,
                      Vector3D a,
                      Vector3D b,
                      Vector3D c,
                      LOFType coeffsFrameLOFType)

Simple constructor for an empiric force. This constructor MUST be used if the frame of definition of vectors A,B and C is a local orbital frame (LOF).

Parameters:

harmonicFactor - the harmonic factor n.

vectorS - the direction whose cross product with ω is used as a reference direction to compute the cos(nωt) and sin(nωt) terms.

a - the vector representing the A coefficient (expressed in the local frame).

b - the vector representing the B coefficient (expressed in the local frame).

c - the vector representing the C coefficient (expressed in the local frame).

coeffsFrameLOFType - the frame of definition of vectors A, B and C.

EmpiricalForce

public EmpiricalForce(int harmonicFactor,
                      Vector3D vectorS,
                      Parameter ax,
                      Parameter ay,
                      Parameter az,
                      Parameter bx,
                      Parameter by,
                      Parameter bz,
                      Parameter cx,
                      Parameter cy,
                      Parameter cz,
                      LOFType coeffsFrameLOFType)

Simple constructor for an empiric force using Parameter for A; B and C coef with a given LOF frame.

Parameters:

harmonicFactor - the harmonic factor

vectorS - the direction vector whose cross product with ω is used as a reference direction to compute the cos(nωt) and sin(nωt) terms.

ax - Parameter for A coefficient along x (ax)

ay - Parameter for A coefficient along Y (ay)

az - Parameter for A coefficient along Z (az)

bx - Parameter for B coefficient along x (bx)

by - Parameter for B coefficient along Y (by)

bz - Parameter for B coefficient along Z (bz)

cx - Parameter for C coefficient along x (cx)

cy - Parameter for C coefficient along Y (cy)

cz - Parameter for C coefficient along Z (cz)

coeffsFrameLOFType - the frame of definition of vectors A, B and C

EmpiricalForce

public EmpiricalForce(int harmonicFactor,
                      Vector3D vectorS,
                      Parameter ax,
                      Parameter ay,
                      Parameter az,
                      Parameter bx,
                      Parameter by,
                      Parameter bz,
                      Parameter cx,
                      Parameter cy,
                      Parameter cz,
                      Frame coeffsFrame)

Simple constructor for an empiric force using Parameter for A; B and C coef with a given frame. WARNING : If the frame of definition of vectors A,B and C is a local orbital frame (LOF), this constructor must NOT be used, acceleration computation would fail.

Parameters:

harmonicFactor - the harmonic factor n.

vectorS - the direction whose cross product with ω is used as a reference direction to compute the cos(nωt) and sin(nωt) terms.

ax - Parameter for A coefficient along x.

ay - Parameter for A coefficient along Y.

az - Parameter for A coefficient along Z.

bx - Parameter for B coefficient along x.

by - Parameter for B coefficient along Y.

bz - Parameter for B coefficient along Z.

cx - Parameter for C coefficient along x.

cy - Parameter for C coefficient along Y.

cz - Parameter for C coefficient along Z.

coeffsFrame - the frame of vectors A, B and C.

EmpiricalForce

public EmpiricalForce(int harmonicFactor,
                      Vector3D vectorS,
                      IParamDiffFunction ax,
                      IParamDiffFunction ay,
                      IParamDiffFunction az,
                      IParamDiffFunction bx,
                      IParamDiffFunction by,
                      IParamDiffFunction bz,
                      IParamDiffFunction cx,
                      IParamDiffFunction cy,
                      IParamDiffFunction cz,
                      LOFType coeffsFrameLOFType)

Simple constructor for an empiric force using parameterizable functions for A; B and C coef with a given LOF frame.

Parameters:

harmonicFactor - the harmonic factor n.

vectorS - the direction whose cross product with ω is used as a reference direction to compute the cos(nωt) and sin(nωt) terms.

ax - Parameterizable function for A coefficient along x (ax)

ay - Parameterizable function for A coefficient along Y (ay)

az - Parameterizable function for A coefficient along Z (az)

bx - Parameterizable function for B coefficient along x (bx)

by - Parameterizable function for B coefficient along Y (by)

bz - Parameterizable function for B coefficient along Z (bz)

cx - Parameterizable function for C coefficient along x (cx)

cy - Parameterizable function for C coefficient along Y (cy)

cz - Parameterizable function for C coefficient along Z (cz)

coeffsFrameLOFType - the frame of definition of vectors A, B and C.

EmpiricalForce

public EmpiricalForce(int harmonicFactor,
                      Vector3D vectorS,
                      IParamDiffFunction ax,
                      IParamDiffFunction ay,
                      IParamDiffFunction az,
                      IParamDiffFunction bx,
                      IParamDiffFunction by,
                      IParamDiffFunction bz,
                      IParamDiffFunction cx,
                      IParamDiffFunction cy,
                      IParamDiffFunction cz,
                      Frame coeffsFrame)

Simple constructor for an empiric force using parameterizable functions for A; B and C coef with a given frame. WARNING : If the frame of definition of vectors A,B and C is a local orbital frame (LOF), this constructor must NOT be used, acceleration computation would fail.

Parameters:

harmonicFactor - the harmonic factor n.

vectorS - the direction whose cross product with ω is used as a reference direction to compute the cos(nωt) and sin(nωt) terms.

ax - Parameterizable function for A coefficient along x.

ay - Parameterizable function for A coefficient along Y.

az - Parameterizable function for A coefficient along Z.

bx - Parameterizable function for B coefficient along x.

by - Parameterizable function for B coefficient along Y.

bz - Parameterizable function for B coefficient along Z.

cx - Parameterizable function for C coefficient along x.

cy - Parameterizable function for C coefficient along Y.

cz - Parameterizable function for C coefficient along Z.

coeffsFrame - the frame of vectors A, B and C.

Method Detail

addContribution

public void addContribution(SpacecraftState state,
                            TimeDerivativesEquations adder)
                     throws PatriusException

Compute the contribution of the force model to the perturbing acceleration.

Specified by:

addContribution in interface ForceModel

Parameters:

state - current state information: date, kinematics, attitude

adder - object where the contribution should be added

Throws:

PatriusException - if some specific error occurs

computeAcceleration

public Vector3D computeAcceleration(SpacecraftState state)
                             throws PatriusException

Compute the acceleration due to the force.

Specified by:

computeAcceleration in interface ForceModel

Parameters:

state - current state information: date, kinematics, attitude

Returns:

acceleration in the SpacecraftState frame

Throws:

PatriusException - if some specific error occurs

computeAcceleration

public Vector3D computeAcceleration(PVCoordinates pv,
                                    LocalOrbitalFrame localFrameValidation,
                                    Vector3D vectorS,
                                    Frame frame,
                                    SpacecraftState state)
                             throws PatriusException

Method to compute the acceleration. This method has been implemented in order to validate the force model only. The reason is that for the validation context, we want to pass to this method some specific values for the local frame and the direction, which depends on external variables (the PV reference ephemeris).

Out of the validation context, one must use the method Vector3D computeAcceleration(final SpacecraftState s)

Parameters:

pv - PV coordinates of the spacecraft for the validation.

localFrameValidation - the local frame to use for the validation.

vectorS - the vector S.

frame - the frame in which the PV coordinates are given.

state - the spacecraft state.

Returns:

acceleration the computed acceleration

Throws:

PatriusException - if an Orekit error occurs

computeCosSin

public double[] computeCosSin(PVCoordinates pv,
                              Vector3D vectorS)

Private method to compute the cos(nwt) and sin(nwt) values.

Parameters:

pv - the pv coordinates.

vectorS - the vector S.

Returns:

the cos(nwt) and sin(nwt) values as an array of doubles.

getLocalFrame

public final Frame getLocalFrame()

Returns:

the local frame in which the vectors A, B and C are defined.

getVectorS

public final Vector3D getVectorS()

Returns:

the direction vector S.

getEventsDetectors

public EventDetector[] getEventsDetectors()

Get the discrete events related to the model.

Specified by:

getEventsDetectors in interface ForceModel

Returns:

array of events detectors or null if the model is not related to any discrete events

addDAccDState

public void addDAccDState(SpacecraftState state,
                          double[][] dAccdPos,
                          double[][] dAccdVel)
                   throws PatriusException

Compute acceleration derivatives with respect to state parameters.

Specified by:

addDAccDState in interface IJacobiansParameterizable

Parameters:

state - spacecraft state

dAccdPos - acceleration derivatives with respect to position

dAccdVel - acceleration derivatives with respect to velocity

Throws:

PatriusException - if derivatives cannot be computed

addDAccDParam

public void addDAccDParam(SpacecraftState state,
                          Parameter param,
                          double[] dAccdParam)
                   throws PatriusException

Compute acceleration derivatives with respect to additional parameters.
AX_COEFFICIENT --> derivatives with respect to the X-component of the A coefficient
AY_COEFFICIENT --> derivatives with respect to the Y-component of the A coefficient
AZ_COEFFICIENT --> derivatives with respect to the Z-component of the A coefficient
BX_COEFFICIENT --> derivatives with respect to the X-component of the B coefficient
BY_COEFFICIENT --> derivatives with respect to the Y-component of the B coefficient
BZ_COEFFICIENT --> derivatives with respect to the Z-component of the B coefficient
CX_COEFFICIENT --> derivatives with respect to the X-component of the C coefficient
CY_COEFFICIENT --> derivatives with respect to the Y-component of the C coefficient
CZ_COEFFICIENT --> derivatives with respect to the Z-component of the C coefficient

Specified by:

addDAccDParam in interface IJacobiansParameterizable

Parameters:

state - spacecraft state

param - the parameter with respect to which derivatives are required

dAccdParam - acceleration derivatives with respect to specified parameters

Throws:

PatriusException - if derivatives cannot be computed

getAx

public IParamDiffFunction getAx()

Get the parametereziable function for the Ax coefficient.

Returns:

the parametereziable function for the Ax coefficient

getAy

public IParamDiffFunction getAy()

Get the parametereziable function for the Ay coefficient.

Returns:

the parametereziable function for the Ay coefficient

getAz

public IParamDiffFunction getAz()

Get the parametereziable function for the Az coefficient.

Returns:

the parametereziable function for the Az coefficient

getBx

public IParamDiffFunction getBx()

Get the parametereziable function for the Bx coefficient.

Returns:

the parametereziable function for the Bx coefficient

getBy

public IParamDiffFunction getBy()

Get the parametereziable function for the By coefficient.

Returns:

the parametereziable function for the By coefficient

getBz

public IParamDiffFunction getBz()

Get the parametereziable function for the Bz coefficient.

Returns:

the parametereziable function for the Bz coefficient

getCx

public IParamDiffFunction getCx()

Get the parametereziable function for the Ax coefficient.

Returns:

the parametereziable function for the Ax coefficient

getCy

public IParamDiffFunction getCy()

Get the parametereziable function for the Cy coefficient.

Returns:

the parametereziable function for the Cy coefficient

getCz

public IParamDiffFunction getCz()

Get the parametereziable function for the Cz coefficient.

Returns:

the parametereziable function for the Cz coefficient

computeGradientPosition

public boolean computeGradientPosition()

This method returns true if the acceleration partial derivatives with respect to position have to be computed.

Specified by:

computeGradientPosition in interface GradientModel

Returns:

true if the derivatives have to be computed, false otherwise

computeGradientVelocity

public boolean computeGradientVelocity()

This method returns true if the acceleration partial derivatives with respect to velocity have to be computed.

Specified by:

computeGradientVelocity in interface GradientModel

Returns:

true if the derivatives have to be computed, false otherwise

checkData

public void checkData(AbsoluteDate start,
                      AbsoluteDate end)
               throws PatriusException

This methods throws an exception if the user did not provide all the required data to perform model call on provided range [start; end]. It is the responsibility of the model implementation to properly throw exceptions (for example DragForce will throw an exception if solar activity data is missing in the range [start, end]).

Specified by:

checkData in interface ForceModel

Parameters:

start - range start date

end - range end date

Throws:

PatriusException - thrown if some data is missing