Package 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:

    • 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

    • 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