Package org.apache.commons.math3.ode

Class JacobianMatrices

java.lang.Object
org.apache.commons.math3.ode.JacobianMatrices
public class JacobianMatrices extends Object
This class defines a set of secondary equations to compute the Jacobian matrices with respect to the initial state vector and, if any, to some parameters of the primary ODE set.

It is intended to be packed into an ExpandableStatefulODE in conjunction with a primary set of ODE, which may be:

In order to compute Jacobian matrices with respect to some parameters of the primary ODE set, the following parameter Jacobian providers may be set:

Since:
3.0
See Also:

  • Constructor Details

    • JacobianMatrices

      public JacobianMatrices(FirstOrderDifferentialEquations fode, double[] hY, String... parameters) throws DimensionMismatchException
      Simple constructor for a secondary equations set computing Jacobian matrices.

      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:
      fode - the primary first order differential equations set to extend
      hY - step used for finite difference computation with respect to state vector
      parameters - parameters to consider for Jacobian matrices processing (may be null if parameters Jacobians is not desired)
      Throws:
      DimensionMismatchException - if there is a dimension mismatch between the steps array hY and the equation dimension

    • JacobianMatrices

      public JacobianMatrices(MainStateJacobianProvider jode, String... parameters)
      Simple constructor for a secondary equations set computing Jacobian matrices.

      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:
      jode - the primary first order differential equations set to extend
      parameters - parameters to consider for Jacobian matrices processing (may be null if parameters Jacobians is not desired)

  • Method Details

    • registerVariationalEquations

      public void registerVariationalEquations(ExpandableStatefulODE expandable) throws DimensionMismatchException, JacobianMatrices.MismatchedEquations
      Register the variational equations for the Jacobians matrices to the expandable set.
      Parameters:
      expandable - expandable set into which variational equations should be registered
      Throws:
      DimensionMismatchException - if the dimension of the partial state does not match the selected equations set dimension
      JacobianMatrices.MismatchedEquations - if the primary set of the expandable set does not match the one used to build the instance
      See Also:

    • addParameterJacobianProvider

      public void addParameterJacobianProvider(ParameterJacobianProvider provider)
      Add a parameter Jacobian provider.
      Parameters:
      provider - the parameter Jacobian provider to compute exactly the parameter Jacobian matrix

    • setParameterizedODE

      public void setParameterizedODE(ParameterizedODE parameterizedOde)
      Set a parameter Jacobian provider.
      Parameters:
      parameterizedOde - the parameterized ODE to compute the parameter Jacobian matrix using finite differences

    • setParameterStep

      public void setParameterStep(String parameter, double hP) throws UnknownParameterException
      Set the step associated to a parameter in order to compute by finite difference the Jacobian matrix.

      Needed if and only if the primary ODE set is a ParameterizedODE.

      Given a non zero parameter value pval for the parameter, a reasonable value for such a step is pval * FastMath.sqrt(Precision.EPSILON).

      A zero value for such a step doesn't enable to compute the parameter Jacobian matrix.

      Parameters:
      parameter - parameter to consider for Jacobian processing
      hP - step for Jacobian finite difference computation w.r.t. the specified parameter
      Throws:
      UnknownParameterException - if the parameter is not supported
      See Also:

    • setInitialMainStateJacobian

      public void setInitialMainStateJacobian(double[][] dYdY0) throws DimensionMismatchException
      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.

      Parameters:
      dYdY0 - initial Jacobian matrix w.r.t. state
      Throws:
      DimensionMismatchException - if matrix dimensions are incorrect

    • setInitialParameterJacobian

      public void setInitialParameterJacobian(String pName, double[] dYdP) throws UnknownParameterException, DimensionMismatchException
      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.

      Parameters:
      pName - parameter name
      dYdP - initial Jacobian column vector with respect to the parameter
      Throws:
      UnknownParameterException - if a parameter is not supported
      DimensionMismatchException - if the column vector does not match state dimension

    • getCurrentMainSetJacobian

      public void getCurrentMainSetJacobian(double[][] dYdY0)
      Get the current value of the Jacobian matrix with respect to state.
      Parameters:
      dYdY0 - current Jacobian matrix with respect to state.

    • getCurrentParameterJacobian

      public void getCurrentParameterJacobian(String pName, double[] dYdP)
      Get the current value of the Jacobian matrix with respect to one parameter.
      Parameters:
      pName - name of the parameter for the computed Jacobian matrix
      dYdP - current Jacobian matrix with respect to the named parameter