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:

  - a `FirstOrderDifferentialEquations`
  - a `MainStateJacobianProvider`
  In order to compute Jacobian matrices with respect to some parameters of the primary ODE set, the following parameter Jacobian providers may be set:
  - a `ParameterJacobianProvider`
  - a `ParameterizedODE`
  Since:
    3.0
  Version:
    $Id: JacobianMatrices.java 1422447 2012-12-16 01:38:40Z psteitz $
  See Also:
    `ExpandableStatefulODE`, `FirstOrderDifferentialEquations`, `MainStateJacobianProvider`, `ParameterJacobianProvider`, `ParameterizedODE`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private class` | `JacobianMatrices.JacobiansSecondaryEquations` Local implementation of secondary equations.
    `private static class` | `JacobianMatrices.MainStateJacobianWrapper` Wrapper class to compute jacobian matrices by finite differences for ODE which do not compute them by themselves.
    `static class` | `JacobianMatrices.MismatchedEquations` Special exception for equations mismatch.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `dirtyParameter` Boolean for selected parameters consistency.
    `private ExpandableStatefulODE` | `efode` Expandable first order differential equation.
    `private int` | `index` Index of the instance in the expandable set.
    `private List<ParameterJacobianProvider>` | `jacobianProviders` FODE with exact parameter Jacobian computation skill.
    `private MainStateJacobianProvider` | `jode` FODE with exact primary Jacobian computation skill.
    `private double[]` | `matricesData` State and parameters Jacobian matrices in a row.
    `private int` | `paramDim` Parameters dimension.
    `private ParameterizedODE` | `pode` FODE without exact parameter Jacobian computation skill.
    `private ParameterConfiguration[]` | `selectedParameters` Selected parameters for parameter Jacobian computation.
    `private int` | `stateDim` Main state vector dimension.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `JacobianMatrices(FirstOrderDifferentialEquations fode, double[] hY, String... parameters)` Simple constructor for a secondary equations set computing Jacobian matrices.
    `JacobianMatrices(MainStateJacobianProvider jode, String... parameters)` Simple constructor for a secondary equations set computing Jacobian matrices.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addParameterJacobianProvider(ParameterJacobianProvider provider)` Add a parameter Jacobian provider.
    `private void` | `checkDimension(int expected, Object array)` Check array dimensions.
    `void` | `getCurrentMainSetJacobian(double[][] dYdY0)` Get the current value of the Jacobian matrix with respect to state.
    `void` | `getCurrentParameterJacobian(String pName, double[] dYdP)` Get the current value of the Jacobian matrix with respect to one parameter.
    `void` | `registerVariationalEquations(ExpandableStatefulODE expandable)` Register the variational equations for the Jacobians matrices to the expandable set.
    `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.
    `void` | `setParameterizedODE(ParameterizedODE parameterizedOde)` Set a parameter Jacobian provider.
    `void` | `setParameterStep(String parameter, double hP)` Set the step associated to a parameter in order to compute by finite difference the Jacobian matrix.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### efode

          private ExpandableStatefulODE efode

      Expandable first order differential equation.

    - #### index

          private int index

      Index of the instance in the expandable set.

    - #### jode

          private MainStateJacobianProvider jode

      FODE with exact primary Jacobian computation skill.

    - #### pode

          private ParameterizedODE pode

      FODE without exact parameter Jacobian computation skill.

    - #### stateDim

          private int stateDim

      Main state vector dimension.

    - #### selectedParameters

          private ParameterConfiguration[] selectedParameters

      Selected parameters for parameter Jacobian computation.

    - #### jacobianProviders

          private List<ParameterJacobianProvider> jacobianProviders

      FODE with exact parameter Jacobian computation skill.

    - #### paramDim

          private int paramDim

      Parameters dimension.

    - #### dirtyParameter

          private boolean dirtyParameter

      Boolean for selected parameters consistency.

    - #### matricesData

          private double[] matricesData

      State and parameters Jacobian matrices in a row.

  - ### Constructor Detail

    - #### 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 Detail

    - #### 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:
        `ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)`

    - #### 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:
        `ParameterizedODE`

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

    - #### checkDimension

          private void checkDimension(int expected,
                            Object array)
                               throws DimensionMismatchException

      Check array dimensions.
      Parameters:
        `expected` - expected dimension
        `array` - (may be null if expected is 0)
      Throws:
        `DimensionMismatchException` - if the array dimension does not match the expected one

Copyright (c) 2003-2013 Apache Software Foundation