org.hipparchus.ode

## Class 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:

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.

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

All Methods
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