Voir la source de User Manual 3.3 Numerical propagation



== Introduction ==
=== Scope ===
This section describes the numerical propagator provided by the Orekit Library: basic orbit propagation, mass, partial derivatives and additional equations.
Analytical propagators are détails in [ORB_ANA_Home Analytical propagation].

=== Javadoc ===
Some of the propagation packages available in the Orekit library are listed here :

|=(% colspan="3" %)Library|=(% colspan="6" %)Javadoc
|(% colspan="3" %)Orekit|(% colspan="6" %)[{{JavaDoc3.3}}/org/orekit/propagation/package-summary.html Package org.orekit.propagation]
|(% colspan="3" %)Orekit|(% colspan="6" %)[{{JavaDoc3.3}}/org/orekit/propagation/numerical/package-summary.html Package org.orekit.propagation.numerical]

=== Links ===
Other useful links can be found here :

(% style="margin-left:30px;list-style-type:square;" %)
* {{siteLink label="Propagation architecture description" jd="OR" suffix="architecture/propagation.html"/}}
* {{siteLink label="Propagation tutorial" jd="OR" suffix="tutorial/propagation.html"/}}.

=== Useful Documents ===
None as of now.

=== Package Overview ===
(% style="text-align: center;" %)
[[[image:Images@propagators2.png]

== Features Description ==
=== Propagators ===
The PATRIUS library offers different propagators :

(% style="margin-left:30px;list-style-type:square;" %)
* Numerical propagator
* Analytical propagators (Keplerian, Eckstein-Hechler, J2 secular, Lyddane secular and long period) (see [ORB_ANA_Home dedicated User Manual])
* Analytical 2D propagator (see [ORB_ANA_Home dedicated User Manual])
* TLE propagator (Two Line Element) (see [ORB_ANA_Home dedicated User Manual])
* Precomputed ephemeris propagator (see [ORB_ANA_Home dedicated User Manual])
* The STELA propagator (see [ORB_GTO_Home dedicated User Manual])

=== Partial Derivatives===
The PATRIUS library offers a comprehensive API that allows computing derivatives using Finite Differences, but also retreiving analytically computed partial derivatives where applicable. The supportParameters() and supportJacobiansParameters() methods from the interfaces given hereunder indicate the user if finite differences and jacobians can be computed.

[[[image:Images@PartialDeriv.png]

== Getting Started ==
{{specialInclusion prefix=$theme_sub section="GettingStarted"/}}

== Contents ==
=== Interfaces ===
|=(% colspan="3" %)Interface|=(% colspan="6" %)Summary|=(% colspan="1" %)Javadoc
|(% colspan="3" %)**AdditionalStateProvider|(% colspan="6" %)This interface represents providers for additional state data beyond SpacecraftState.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/AdditionalStateProvider.html ...]
|(% colspan="3" %)**BoundedPropagator|(% colspan="6" %)This interface is intended for ephemerides valid only during a time range.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/BoundedPropagator.html ...]
|(% colspan="3" %)**Propagator|(% colspan="6" %)This interface provides a way to propagate an orbit at any time.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/Propagator.html ...]

'''Interfaces specific to Numerical propagators'''

|(% colspan="3" %)**AdditionalEquations|(% colspan="6" %)This interface allows users to add their own differential equations to a numerical propagator.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/numerical/AdditionalEquations.html ...]
|(% colspan="3" %)**ModeHandler|(% colspan="6" %)Common interface for all propagator mode handlers initialization.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/numerical/ModeHandler.html ...]
|(% colspan="3" %)**TimeDerivativesEquations|(% colspan="6" %)Interface summing up the contribution of several forces into orbit and mass derivatives.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/numerical/TimeDerivativesEquations.html ...]

=== Classes ===
|=(% colspan="3" %)Class|=(% colspan="6" %)Summary|=(% colspan="1" %)Javadoc
|(% colspan="3" %)'''SpacecraftState'''|(% colspan="6" %)This class is the representation of a complete state holding orbit, attitude for forces and for events computation and additional states at a given date.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/SpacecraftState.html ...]
|(% colspan="3" %)'''NumericalPropagator'''|(% colspan="6" %)This class propagates SpacecraftState using numerical integration.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/numerical/NumericalPropagator.html ...]
|(% colspan="3" %)'''AttitudeEquation'''|(% colspan="6" %)This class represents attitude differential equations.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/numerical/AttitudeEquation.html ...]
|(% colspan="3" %)'''IntegratedEphemeris'''|(% colspan="6" %)This class stores sequentially generated orbital parameters for later retrieval.|(% colspan="1" %)[{{JavaDoc3.3}}/org/orekit/propagation/precomputed/IntegratedEphemeris.html ...]
ropagator.html"/}}
|(% colspan="3" %)'''SimpleAdditionalStateProvider'''|(% colspan="6" %)This class implements AdditionalStateProvider interface. It simply handles a list of dates associated to additional state vectors. For a given date it returns the associated additional state vector or a propagation exception if this date is not found. This class will be basically used with a PVCoordinatePropagator. |(% colspan="1" %)[{{JavaDoc3.3}}/fr/cnes/sirius/patrius/propagation/SimpleAdditionalStateProvider.html ...]

=== Using the Propagators ====

For more information about the propagators of Orekit, please refer to the {{siteLink label="propagation architecture description" jd="OR" suffix="architecture/propagation.html"/}} and the {{siteLink label="propagation tutorial" jd="OR" suffix="tutorial/propagation.html"/}}.


==== Propagation mode =====

There are three different propagation modes : slave, master and ephemeris generation.

Set to'''slave mode''', the propagator computes the final orbit for a given date and returns it to the user without any intermediate feedback.

When the user wants to call some specific function at the end of each successful step or at the end of a given fixed step during the integration, the propagator has to be set to'''master mode''' and a step handler which represents the specific function has to be designed by the user and given to the propagator.

The'''ephemeris generation mode''' is used when the user needs random access to the orbit state at any date after the propagation. Be aware that this mode may be memory intensive since all intermediate results are stored.

See : {{siteLink label="propagation mode description" jd="OR" suffix="architecture/propagation.html"/}}. Note : Two errors are in that tutorial : getITRF2005() was replaced by getITRF(). VisibilityDetector was replaced by VisibilityFromStationDetector

|=(% colspan="3" %)Use case|=(% colspan="6" %)without dense output|=(% colspan="9" %)with dense output|=(% colspan="12" %)with event detection|=(% colspan="15" %)with step handler
|(% colspan="3" %)slave|(% colspan="6" %)+ faster than the others since it has no step handler|(% colspan="9" %)- not adapted when it comes to generate a dense output|(% colspan="12" %)+ adapted|(% colspan="15" %)- not adapted
|(% colspan="3" %)master|(% colspan="6" %)- not really adapted|(% colspan="9" %)- not really adapted (could be adapted with a specific step handler)|(% colspan="12" %)+ adapted|(% colspan="15" %)+ adapted
|(% colspan="3" %)ephemeris generation|(% colspan="6" %)- not really adapted|(% colspan="9" %)+ adapted|(% colspan="12" %)+ adapted|(% colspan="15" %)- not adapted

NB : To get a dense output, the user should not propagate on a series of time intervals to get intermediate results because at the end of any propagation, the last step is likely readjusted to reach exactly the propagation end date. This behavior differs from the expected one : the integrator parametrization is bypassed, this behavior should remain rare.

==== Propagation frame =====

Both analytical and numerical propagators are able to propagate orbits which are defined in a not inertial or pseudo-inertial frame.
However, the propagation has to be performed in an inertial frame, as a result:
* If initial state frame is inertial and user did not specify propagation frame, then propagation will be performed in initial state frame
* If initial state frame is not inertial and user did not specify propagation frame, then an exception will be thrown
* If the user specified a propagation frame, then propagation is performed in specified frame, independently of initial state frame

Propagation frame can be specified using method <code>setOrbitFrame(final Frame frame)</code> of propagators.

==== Propagation =====

See : [FDY_SST_Home SpacecraftState description]

Numerical propagation can be executed in cartesian, equinoctial, keplerian and circular parameters. By default, equinoctial parameters are used.

A loss of accuracy occurs when a numerical propagator using a fixed step RK4 integrator propagates a bulletin using cartesian parameters.

===== Basic propagation =====
Here is presented a basic instanciation of the numerical propagator with an input state built from an [{{JavaDoc3.3}}''org/orekit/orbits/Orbit.html orbit] and a [{{JavaDoc3.3}}''org/orekit/propagation/MassProvider.html mass provider].

See : [SPC_VBU_Home Building assembly]

<syntaxhighlight lang="java">
// Initial orbit
final AbsoluteDate date = new AbsoluteDate(2000, 3, 1, TimeScalesFactory.getTT());
final double mu = Constants.EGM96_EARTH_MU;
final Frame referenceFrame = FramesFactory.getGCRF();
final Orbit orbit = new KeplerianOrbit(7500000, 0.001, 0.40, 0, 0, 0,PositionAngle.MEAN, referenceFrame, date, mu);

// Initial mass provider
final MassProvider massModel = new MassModel(assembly);
        
// Initial SpacecraftState 
final SpacecraftState initialState = new SpacecraftState(orbit, massModel);
               
// integrator tolerances for the orbital parameters
final double[] vecAbsoluteTolerance = { 1e-5, 1e-5, 1e-5, 1e-8, 1e-8, 1e-8};
final double[] vecRelativeTolerance = { 1e-10, 1e-10, 1e-10, 1e-10, 1e-10, 1e-10};
// integrator and propagator
final FirstOrderIntegrator integrator = new DormandPrince853Integrator(0.01, 500., vecAbsoluteTolerance, vecRelativeTolerance);
final NumericalPropagator p = new NumericalPropagator(integrator);

// Propagate in cartesian parameters
p.setOrbitType(OrbitType.CARTESIAN);

// Initialize state
p.setInitialState(initialState);

// add equations associated with mass model : compulsory if maneuvers are present !!! Mass provider must be mass provider used in force models.
p.setMassProviderEquation(massModel);

// propagation
final SpacecraftState finalState = p.propagate(date.shiftedBy(propagationDuration));
</syntaxhighlight>

===== Using Dormand-Prince integrators =====

Adaptive stepsize Dormand-Prince integrators are commonly use in space mechanics. A 5th order and a 8th order Dormand-Prince integrators are available in Commons-Math.
They have the particularity to have an adaptive step size: during the integration, the integrator tries to keep the integration step as large as possible to save some computation time. The integrator computes the integration step to use by estimating the error made compared to a threshold. The smaller the stepsize, the higher the dynamics of the system.
As a result, the user is required to provide the following information:
* The minimum and maximum allowed step size. The minimum step size should be small enough to handle any integration of the user dynamics. The maximum step size should be high enough to reduce computation times when the dynamics is slow.
* The absolute and relative tolérances. These tolerances are used to estimate the current integration step: the integrator reduces the step size until estimated error is below these tolerances. Warning: it does not mean the accuracy of your integration will be below these tolerances! But only that over one integration step, the use of this integrator should not degrade the accuracy of the result more than the fixed tolerance.

As a rule of thumb, the following instantiation is good for orbit dynamics (stepsize in [0.01s, 500s], absolute tolerance being { 1e-5, 1e-5, 1e-5, 1e-8, 1e-8, 1e-8} and relative tolerance being 1e-10:

<syntaxhighlight lang="java">
final double[] vecAbsoluteTolerance = { 1e-5, 1e-5, 1e-5, 1e-8, 1e-8, 1e-8};
final double[] vecRelativeTolerance = { 1e-10, 1e-10, 1e-10, 1e-10, 1e-10, 1e-10};
final FirstOrderIntegrator integrator = new DormandPrince853Integrator(0.01, 500., vecAbsoluteTolerance, vecRelativeTolerance);
</syntaxhighlight>

When dealing with another dynamics (semi-analytical propagation, etc.), other parameterization may be more suitable.
Alike the code example above, one has to specify in which parameters type the propagation has to be performed, calling <code> setOrbitType(OrbitType)</code> on 
the propagator (Orbitype.CARTESIAN for cartesian parameters for example).

'''Important notice'''

Dormand-Prince integrators (as well as Higham-hall integrator) uses only states whose tolerance has been defined to estimate error and deduce integration step.
Tolerance is defined if not set to [absolute tolerance = +inf, relative tolerance = 0].
By default, tolerances are not set for partial derivatives. As a result, propagation with or without partial dérivatives will return the exact same PV coordinates.

===== Adding mass to state vector =====

Mass is a particular additional state, since it is common state in orbital propagation. Propagation with other additional states is detailed in next section.

Including mass states in propagation requires two step:
* Add mass initial states to state vector:

This is performed by providing a [{{JavaDoc3.3}}''org/orekit/propagation/MassProvider.html MassProvider]  to the initial [{{JavaDoc3.3}}''org/orekit/propagation/SpacecraftState.html SpacecraftState]. Mass information is automaticaly stored as additional states of the SpacecraftState.

* Add mass equations to propagator:

For each mass additional state associated with the [{{JavaDoc3.3}}''org/orekit/propagation/SpacecraftState.html SpacecraftState], the corresponding additional equation are added to the [{{JavaDoc3.3}}''org/orekit/propagation/numerical/NumericalPropagator.html numerical propagator] using'''''setMassProviderEquation(MassProvider)'''''.
Important notice: this method should be called only once and provided mass provider must be mass provider used in force models for global propagation consistency.

An example using mass propagation is detailed in next section.

===== Propagation with additional states =====

It is possible to propagate the complete SpacecraftState including additional states. It could be particularly interesting to propagate additional states if, for example, some other variables need the dynamical spacecraft state to be computed. These additional states are related to differential equations that have to be given to the numerical propagator. They will be integrated with the same integrator scheme as the motion equations and at the same time. It is also possible to define variation tolerance values specifically for each additional state, so that a variable step integrator can take these into account and reduce its step to compute additional states accurately.

In practical terms, the user has to build the additional equation by implementing the interface "'''''AdditionalEquation'''''". 

These additional equations are given to the propagator thanks to the following methods :
'''*''addAdditionalEquation(AdditionalEquation)'''''
'''*''addAttitudeEquation(AttitudeEquation)''''' (see next part)
'''*''setMassProviderEquation(MassProvider)''''' (This method should be called only once, see above section)

The initial value of the additional states are stored in the initial SpacecraftState given to the propagator. The method "'''''setAdditionalStateTolerance(String, double[], double[])'''''" may be used to add variation tolerance values (absolute and relative) for the state. An additional equation should be identified by the user in an unequivocal way by a name (String) which is a mandatory attribute. The link between the additional state and the additional equation is done at the beginning of the propagation. At the beginning of the propagation, it is also checked that the additional states size correspond with the additional tolerances fixed in the propagator. 
The following example shows how to propagate a SpacecraftState with a mass and one additional state. 

<syntaxhighlight lang="java">
// Initial SpacecraftState 
SpacecraftState initialState = new SpacecraftState(orbit, massModel);

// add additional state (of size 3) to the SpacecraftState
final String stateName = "state1";
initialState = initialState.addAdditionalState(stateName, new double[]{1., 2., 3.});

// Initialize state
p.setInitialState(initialState);

// add equations associated with mass model (Mass provider must be mass provider used in force models)
p.setMassProviderEquation(massModel);

// add additional equation associated with the additional state
p.addAdditionalEquations(additionalEquation);

// tolerances (of size 3) for the additional state :
final double[] absoluteTol = { 1e-5, 1e-5, 1e-5 };
final double[] relativeTol = { 1e-10, 1e-10, 1e-10 };
p.setAdditionalStateTolerance(stateName, absoluteTol, relativeTol);

// Propagate in cartesian parameters
p.setOrbitType(OrbitType.CARTESIAN);

// propagation
final SpacecraftState finalState = p.propagate(date.shiftedBy(propagationDuration));
</syntaxhighlight>

It is possible to get a feedback of the additional states evolution throughout the propagation. To that purpose, the user should create a step handler which implements the interface "'''''OrekitStepHandler'''''" and set the propagator to "master mode". The main method of the step handler is the method "'''''handleStep(OrekitStepInterpolator, boolean)'''''" which has to be designed by the user according to what he wants to do at the end of each integration step. For example, in order to get a feedback of the additional states once the propagation is performed, the user could design this method in the following manner :

<syntaxhighlight lang="java">
        @Override
        public void handleStep(final OrekitStepInterpolator interpolator, final boolean isLast)
                throws PropagationException {

            SpacecraftState currentState;
            Map<String, double[]> addStates;
            try {

                currentState = interpolator.getInterpolatedState();
                addStates = currentState.getAdditionalStates();

                datesList.add(currentState .getDate());
                pv.add(currentState.getPVCoordinates());
                addStatesMap.add(currentState.getAdditionalStates());

            } catch (OrekitException e) {
                e.printStackTrace();
            }
        }
</syntaxhighlight>

If you want to keep the provided interpolator for later use, add in handleStep method:

<syntaxhighlight lang="java">
((AdaptedStepHandler) interpolator).copy();
</syntaxhighlight>

To continue the previous example :

<syntaxhighlight lang="java">
// propagation
final StateObserver stepHandler = new StateObserver();

p.setMasterMode(stepHandler);

p.resetInitialState(new SpacecraftState(orbit));

p.propagate(date.shiftedBy(propagationDuration));

final List<AbsoluteDate> dates = stepHandler.getDatesList();
final List<Double> mass = stepHandler.getAddStateList();
final List<PVCoordinates> pv = stepHandler.getDatesList();
</syntaxhighlight>

===== Propagation of the attitudes : two possible treatments =====
To propagate the [{{JavaDoc3.3}}//org/orekit/attitudes/Attitude.html Attitude], two treatments could be applied : 
* compute the attitude with an [{{JavaDoc3.3}}''org/orekit/attitudes/AttitudeProvider.html AttitudeProvider] :'''''setAttitudeProvider(AttitudeProvider)//'''.
It is possible to deals with : 
''' a single attitude by calling'''''setAttitudeProvider(AttitudeProvider)''**
''' two attitudes by calling'''''setAttitudeProviderForces(AttitudeProvider)''''' or '''''setAttitudeProviderEvents(AttitudeProvider)'''''. It is not possible to call '''''setAttitudeProvider(AttitudeProvider)''''' and '''''setAttitudeProviderForces(AttitudeProvider)''''' (or '''''setAttitudeProviderEvents(AttitudeProvider)''**)
* propagate the attitude as a 7-dimension additional state :'''''addAttitudeEquation(AttitudeEquation)'''''.
In practical terms, the user has to build the additional equation by extending the abstract class [{{JavaDoc3.3}}''org/orekit/propagation/numerical/AttitudeEquation.html AttitudeEquation], call'''''addAttitudeEquation(AttitudeEquation)//'''. The additional state corresponding with the attitude is automatically add to the additional states map of the initial SpacecraftState. An AttitudeEquation is associated with an AttitudeType : 
** ATTITUDE : if a single attitude treatment is done. If the user wants to propagate only one attitude.
** ATTITUDE_FORCES and ATTITUDE_EVENTS : if a double attitude treatment is done. If the user wants to propagate the attitude for forces computation and the attitude for events computation. See : [FDY_SST_Home SpacecraftState description]
It is not possible to add an attitude equation in type ATTITUDE and one in type ATTITUDE_FORCES or ATTITUDE_EVENTS.

The following example shows how to propagate a SpacecraftState with an attitude added to the additional states map.
<syntaxhighlight lang="java">
// Initial SpacecraftState
SpacecraftState initialState = new SpacecraftState(orbit, attitude);
// Initialize state
p.setInitialState(initialState);
// add equation associated with the attitude
p.addAttitudeEquation(new AttitudeEquation(AttitudeType.ATTITUDE) {
   public void computeDerivatives(SpacecraftState s, TimeDerivativesEquations adder) throws OrekitException {...}
});
// propagation
final SpacecraftState finalState = p.propagate(date.shiftedBy(propagationDuration));
</syntaxhighlight>

The following example shows how to propagate a SpacecraftState with two attitude (one added to the additional states map, the other computed with the AttitudeProvider).
<syntaxhighlight lang="java">
// Initial SpacecraftState
SpacecraftState initialState = new SpacecraftState(orbit, attitudeForces, attitudeEvents);
// Initialize state
p.setInitialState(initialState);

// add equations associated with attitude for forces computation
p.addAttitudeEquation(new AttitudeEquation(AttitudeType.ATTITUDE_FORCES) {
    public void computeDerivatives(SpacecraftState s, TimeDerivativesEquations adder) throws OrekitException {...}
});

// add attitude provider for events computation : attitude law aligned with EME2000
final AttitudeProvider attProv = new ConstantAttitudeLaw(FramesFactory.getEME2000(), Rotation.IDENTITY);
p.setAttitudeProviderEvents(attProv);

// propagation
final SpacecraftState finalState = p.propagate(date.shiftedBy(propagationDuration));
</syntaxhighlight>


==== Partial derivatives equations =====

OREKIT provides an implementation of the interface "'''''AdditionalEquation'''''". This set of additional equations computes the partial derivatives of the state (orbit) with respect to initial state and force models parameters. 

This set of equations is automatically added to a numerical propagator in order to compute partial derivatives of the orbit during a propagation. This is useful in orbit determination applications. The force models implement analytical methods to compute partial derivatives with respect to state or force models parameters. If not, the finite difference method is applied. 

Partial derivatives with respect to state (position or velocity) can be tuned or disabled:
* They can be disabled for every force inheriting <code>GradientModel</code> using the provided constructors.
* For potential models (excluding Droziner model), order and degree can be tuned differently for acceleration computation and partial dérivatives computation.

The general principles are described in the above section'''''Additional state'''''. An example is given here to see how to propagate jacobians throughout an orbit. We call '''''dYdY0''''' the partial derivatives of the state with respect to initial state and '''''dYdP''''' the partial derivatives of the state with respect to force models parameters.

First, the user has to add the partial derivatives equations of the state. Upon construction, this set of equations is automatically added to the propagator by calling its "'''''NumericalPropagator.addAdditionalEquations(AdditionalEquations)'''''" method. So there is no need to call this method explicitly for these equations.
 
After that, the user has to set the initial value of the jacobians with respect to state and parameters, using the "'''''PartialDerivativesEquations.setInitialJacobians(SpacecraftState, int)'''''" method (or "'''''setInitialJacobians(SpacecraftState, double[][])'''''"). This method is equivalent to call "'''''setInitialJacobians(SpacecraftState, double[][], double[][])'''''" with'''''dYdY0''''' set to the identity matrix and '''''dYdP''''' set to a zero matrix. Other similar methods are provided if the user wants to specifically set initial Jacobians with respect to state or to one particular parameter ("'''''setInitialJacobians(SpacecraftState, Parameter, double[])'''''".
 
To use the jacobians, it is necessary to define a mapper between one-dimensional additional state and two-dimensional jacobians. 

<syntaxhighlight lang="java">

// we assume that a propagator "propagator" has been built with its initial state "initialState"

// add the partial derivatives of the state with respect to initial state,
// with a name to identify it     
final PartialDerivativesEquations partials = new PartialDerivativesEquations("PDE", propagator);

// set the initial value of the jacobians
// here state dimension = 6 and parameter dimension = 0
partials.setInitialJacobians(initialState, 0);
// get a mapper between two-dimensional jacobians and one-dimensional additional state
// with the same name as the instance
final JacobiansMapper mapper = partials.getMapper();
[...]
</syntaxhighlight>

In order to get the jacobians throughout the propagation, the user can create a step handler which implements the interface "'''''OrekitStepHandler'''''" and set the propagator to "master mode". The example shows how to get jacobians during the propagation. The following class "'''''JacobiansHandler'''''" implements "'''''OrekitStepHandler'''''" (the main methods are given hereafter).

<syntaxhighlight lang="java">

        // step handler constructor
        public JacobiansHandler(final JacobiansMapper inMapper, final AbsoluteDate inDate) {
            this.mapper = inMapper;
            this.date = inDate;
            dYdY0 = new double[mapper.getStateDimension()][mapper.getStateDimension()];
            dYdP = new double[mapper.getStateDimension()][mapper.getParameters()];
        }


        @Override
        public void handleStep(final OrekitStepInterpolator interpolator, final boolean isLast)
                throws PropagationException {
            try {
                if (date == null) {
                    // we want to pick up the Jacobians at the end of last step
                    if (isLast) {
                        // set the interpolated date which is the current grid date (the last step)
                        interpolator.setInterpolatedDate(interpolator.getCurrentDate());
                    }
                } else {
                    // we want to pick up some intermediate Jacobians
                    final double dt0 = date.durationFrom(interpolator.getPreviousDate());
                    final double dt1 = date.durationFrom(interpolator.getCurrentDate());
                    if (dt0* dt1 > 0) {
                        // the current step does not cover the pickup date
                        return;
                    } else {
                        // set the interpolated date
                        interpolator.setInterpolatedDate(date);
                    }
                }
                // get the interpolated state at the current interpolated date
                final SpacecraftState state = interpolator.getInterpolatedState();
                // get the Jacobian with respect to state-> dYdY0 array
                dYdY0 = mapper.getStateJacobian(state);
                // get the Jacobian with respect to parameters-> dYdP array
                dYdP = mapper.getParametersJacobian(state);
                // get the Jacobian with respect to parameter 1-> dYdP1 array
                dYdP1 = mapper.getParametersJacobian(parameter1, state);
            } catch (PropagationException pe) {
                throw pe;
            } catch (OrekitException oe) {
                throw new PropagationException(oe);
            }

        } 
        
        // Method to get the jacobian with respect to initial state
        public double[][] getdYdY0() {
            return dYdY0;
        }

</syntaxhighlight>


To continue with the main program, a way to get the jacobians and to use it could be the following:

<syntaxhighlight lang="java">
[...]
        // add a step handler to get the jacobian matrix corresponding to the last date
        // can be used to get the jacobians corresponding to a given date
        final JacobiansHandler jacobiHandler = new JacobiansHandler(mapper, initialDate.shiftedBy(dt));
        propagator.setMasterMode(jacobiHandler);

        // propagate the orbit until initialDate+dt
        final SpacecraftState finalState = propagator.propagate(initialDate.shiftedBy(dt));

        // get the jacobian matrix with respect to initial state at the final date
        final double[][] dYdY0 = jacobiHandler.getdYdY0();

        // examples using jacobians...

        // convert dYdY0 into a RealMatrix
        final RealMatrix mat = new Array2DRowRealMatrix(dYdY0);

        // invert mat, using LU decomposition
        final RealMatrix matInverse = new LUDecomposition(mat).getSolver().getInverse();
[...]
        
</syntaxhighlight>

Note : the dYdY0 terms are given according to the orbit type known to the propagator. If one wants to compute the partial derivatives with equinoctial parameters, then one should specify it to the propagator first, using the method NumericalPropagator.setOrbitType(OrbitType). Additionally, it is also important to specify the correct orbit position angle type (true, mean or eccentric- if the orbit requires it), using the methods NumericalPropagator.setPositionAngleType(PositionAngle).


== Tutorials ==
=== Tutorial 1 ===
{{specialInclusion prefix=$theme_sub section="Tuto1"/}}

=== Tutorial 2 ===
{{specialInclusion prefix=$theme_sub section="Tuto2"/}}

== [[File:lightBulb.png]] Tips & Tricks ==
|= '''Propagator''' |= '''Constructor''' |='''Comment'''
|[{{JavaDoc3.3}}/org/orekit/propagation/analytical/KeplerianPropagator.html KeplerianPropagator]|KeplerianPropagator(Orbit, AttitudeProvider)|This constructor internally creates a SpacecraftState instance with the user specified AttitudeProvider. ''Note :'' if the setAttitudeProvider method is used, the initialState is not updated with the new AttitudeProvider. In that case, the user should manually create a new SpacecraftState instance and give it the propagator using the resetInitialState method. Finally, one should not that the standard gravitational parameter and the spacecraft mass are not important here because this propagator will only change the mean anomaly depending on the time elapsed since the orbit date.
|[{{JavaDoc3.3}}/org/orekit/propagation/numerical/NumericalPropagator.html NumericalPropagator]|NumericalPropagator(FirstOrderIntegrator)|After creating the NumericalPropagator instance, the user must provide an initial SpacecraftState. The user can also provide more parameters, such as AttitudeProviders, ForceModels and so on (see javadoc for more details).