org.hipparchus.ode

Class VariationalEquation

java.lang.Object

org.hipparchus.ode.VariationalEquation

public class VariationalEquation
extends Object

This class defines a set of secondary equations to compute the global Jacobian matrices with respect to the initial state vector and, if any, to some parameters of the primary ODE set.

The primary set of ODE for which Jaobian matrices are requested may be:

• a full-fledged ODEJacobiansProvider that computes by itself both the ODE and its local partial derivatives,
• a simple OrdinaryDifferentialEquation which must therefore be completed with a finite differences configuration to compute local partial derivatives (so-called internal differentiation).

As the variational equation automatically inserts secondary differential equations, in the expandable ODE, data for initial state must also be inserted before integration and matrices result must be extracted after integration. This implies a precise scheduling of the calls to the various methods of this class. The proper scheduling is the following one:

   // set up equations
   ODEJacobiansProvider jode       = new MyODE(...);
   ExpandableODE        expandable = new Expandable(jode);
   VariationalEquation  ve         = new VariationalEquation(expandable, jode);

   // set up initial state
   ODEState initWithoutDerivatives = new ODEState(t0, y0);
   ve.setInitialMainStateJacobian(dYdY0); // only needed if the default identity matrix is not suitable
   ve.setInitialParameterJacobian(name, dYdP); // only needed if the default zero matrix is not suitable
   ODEState initWithDerivatives = ve.setUpInitialState(initWithoutDerivatives);

   // perform integration on the expanded equations with the expanded initial state
   ODEStateAndDerivative finalState = integrator.integrate(expandable, initWithDerivatives, finalT);

   // extract Jacobian matrices
   dYdY0 = ve.extractMainSetJacobian(finalState);
   dYdP  = ve.extractParameterJacobian(finalState, name);
 

The most important part is to not forget to call setUpInitialState(ODEState) to add the secondary state with the initial matrices to the ODEState used in the integrate method. Forgetting to do this and passing only a ODEState without the secondary state set up will trigger an error as the state vector will not have the correct dimension.

See Also:

ExpandableODE, ODEJacobiansProvider, OrdinaryDifferentialEquation, NamedParameterJacobianProvider, ParametersController

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VariationalEquation.MismatchedEquations Special exception for equations mismatch.

Constructor Summary

Constructors

Constructor and Description
VariationalEquation(ExpandableODE expandable, ODEJacobiansProvider jode) Build variational equation using analytical local partial derivatives.
VariationalEquation(ExpandableODE expandable, OrdinaryDifferentialEquation ode, double[] hY, ParametersController controller, ParameterConfiguration... paramsAndSteps) Build variational equation using finite differences for local partial derivatives.

Method Summary

Modifier and Type	Method and Description
double[][]	extractMainSetJacobian(ODEState state) Extract the Jacobian matrix with respect to state.
double[]	extractParameterJacobian(ODEState state, String pName) Extract the Jacobian matrix with respect to one parameter.
void	setInitialMainStateJacobian(double[][] dYdY0) Set the initial value of the Jacobian matrix with respect to state.
void	setInitialParameterJacobian(String pName, double[] dYdP) Set the initial value of a column of the Jacobian matrix with respect to one parameter.
ODEState	setUpInitialState(ODEState initialState) Set up initial state.

Methods inherited from class java.lang.Object

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

Constructor Detail

VariationalEquation

public VariationalEquation(ExpandableODE expandable,
                           OrdinaryDifferentialEquation ode,
                           double[] hY,
                           ParametersController controller,
                           ParameterConfiguration... paramsAndSteps)
                    throws VariationalEquation.MismatchedEquations

Build variational equation using finite differences for local partial derivatives.

Parameters:

expandable - expandable set into which variational equations should be registered

ode - base ordinary differential equation for which Jacobians matrices are requested

hY - step used for finite difference computation with respect to state vector

controller - controller to change parameters

paramsAndSteps - parameters and steps to compute the Jacobians df/dp

Throws:

VariationalEquation.MismatchedEquations - if the primary set of the expandable set does not match the ode

VariationalEquation

public VariationalEquation(ExpandableODE expandable,
                           ODEJacobiansProvider jode)
                    throws VariationalEquation.MismatchedEquations

Build variational equation using analytical local partial derivatives.

Parameters must belong to the supported ones given by Parameterizable.getParametersNames(), so the primary set of differential equations must be Parameterizable.

Note that each selection clears the previous selected parameters.

Parameters:

expandable - expandable set into which variational equations should be registered

jode - the primary first order differential equations set to extend

Throws:

VariationalEquation.MismatchedEquations - if the primary set of the expandable set does not match the ode

Method Detail

setInitialMainStateJacobian

public void setInitialMainStateJacobian(double[][] dYdY0)
                                 throws MathIllegalArgumentException

Set the initial value of the Jacobian matrix with respect to state.

If this method is not called, the initial value of the Jacobian matrix with respect to state is set to identity.

This method must be called before setUpInitialState(ODEState)

Parameters:

dYdY0 - initial Jacobian matrix w.r.t. state

Throws:

MathIllegalArgumentException - if matrix dimensions are incorrect

setInitialParameterJacobian

public void setInitialParameterJacobian(String pName,
                                        double[] dYdP)
                                 throws MathIllegalArgumentException

Set the initial value of a column of the Jacobian matrix with respect to one parameter.

If this method is not called for some parameter, the initial value of the column of the Jacobian matrix with respect to this parameter is set to zero.

This method must be called before setUpInitialState(ODEState)

Parameters:

pName - parameter name

dYdP - initial Jacobian column vector with respect to the parameter

Throws:

MathIllegalArgumentException - if a parameter is not supported

MathIllegalArgumentException - if the column vector does not match state dimension

setUpInitialState

public ODEState setUpInitialState(ODEState initialState)

Set up initial state.

This method inserts the initial Jacobian matrices data into an ODE state by overriding the additional state components corresponding to the instance. It must be called prior to integrate the equations.

This method must be called after setInitialMainStateJacobian(double[][]) and setInitialParameterJacobian(String, double[]).

Parameters:

initialState - initial state, without the initial Jacobians matrices

Returns:

a new instance of initial state, with the initial Jacobians matrices properly initialized

extractMainSetJacobian

public double[][] extractMainSetJacobian(ODEState state)

Extract the Jacobian matrix with respect to state.

Parameters:

state - state from which to extract Jacobian matrix

Returns:

Jacobian matrix dY/dY0 with respect to state.

extractParameterJacobian

public double[] extractParameterJacobian(ODEState state,
                                         String pName)

Extract the Jacobian matrix with respect to one parameter.

Parameters:

state - state from which to extract Jacobian matrix

pName - name of the parameter for the computed Jacobian matrix

Returns:

Jacobian matrix dY/dP with respect to the named parameter