org.apache.commons.math3.ode
Class JacobianMatrices

java.lang.Object
  extended by 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
Version:
$Id: JacobianMatrices.java 1422447 2012-12-16 01:38:40Z psteitz $
See Also:
ExpandableStatefulODE, FirstOrderDifferentialEquations, MainStateJacobianProvider, ParameterJacobianProvider, ParameterizedODE

Nested Class Summary
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
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
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
 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