Top Description Inners Fields Constructors Methods
org.apache.commons.math3.ode

public Class JacobianMatrices

extends Object
Class Inheritance
Imports
java.lang.reflect.Array, java.util.ArrayList, .Arrays, .List, org.apache.commons.math3.exception.DimensionMismatchException, .MathIllegalArgumentException, .MaxCountExceededException, org.apache.commons.math3.exception.util.LocalizedFormats

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
ExpandableStatefulODE, FirstOrderDifferentialEquations, MainStateJacobianProvider, ParameterJacobianProvider, ParameterizedODE

Nested and Inner Type Summary

Modifier and TypeClass 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.

public static class
JacobianMatrices.MismatchedEquations

Special exception for equations mismatch.

Field Summary

Modifier and TypeField 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

AccessConstructor and Description
public
JacobianMatrices(final FirstOrderDifferentialEquations
the primary first order differential equations set to extend
fode
,
final double[]
step used for finite difference computation with respect to state vector
hY
,
final String...
parameters to consider for Jacobian matrices processing (may be null if parameters Jacobians is not desired)
parameters
)

Simple constructor for a secondary equations set computing Jacobian matrices.

public
JacobianMatrices(final MainStateJacobianProvider
the primary first order differential equations set to extend
jode
,
final String...
parameters to consider for Jacobian matrices processing (may be null if parameters Jacobians is not desired)
parameters
)

Simple constructor for a secondary equations set computing Jacobian matrices.

Method Summary

Modifier and TypeMethod and Description
public void
addParameterJacobianProvider(final ParameterJacobianProvider
the parameter Jacobian provider to compute exactly the parameter Jacobian matrix
provider
)

Add a parameter Jacobian provider.

private void
checkDimension(final int
expected dimension
expected
,
final Object
(may be null if expected is 0)
array
)

Check array dimensions.

public void
getCurrentMainSetJacobian(final double[][]
current Jacobian matrix with respect to state.
dYdY0
)

Get the current value of the Jacobian matrix with respect to state.

public void
getCurrentParameterJacobian(String
name of the parameter for the computed Jacobian matrix
pName
,
final double[]
current Jacobian matrix with respect to the named parameter
dYdP
)

Get the current value of the Jacobian matrix with respect to one parameter.

public void
registerVariationalEquations(final ExpandableStatefulODE
expandable set into which variational equations should be registered
expandable
)

Register the variational equations for the Jacobians matrices to the expandable set.

public void
setInitialMainStateJacobian(final double[][]
initial Jacobian matrix w.r.t. state
dYdY0
)

Set the initial value of the Jacobian matrix with respect to state.

public void
setInitialParameterJacobian(final String
parameter name
pName
,
final double[]
initial Jacobian column vector with respect to the parameter
dYdP
)

Set the initial value of a column of the Jacobian matrix with respect to one parameter.

public void
setParameterizedODE(final ParameterizedODE
the parameterized ODE to compute the parameter Jacobian matrix using finite differences
parameterizedOde
)

Set a parameter Jacobian provider.

public void
setParameterStep(final String
parameter to consider for Jacobian processing
parameter
,
final double
step for Jacobian finite difference computation w.r.t. the specified parameter
hP
)

Set the step associated to a parameter in order to compute by finite difference the Jacobian matrix.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

dirtyParameterback to summary
private boolean dirtyParameter

Boolean for selected parameters consistency.

efodeback to summary
private ExpandableStatefulODE efode

Expandable first order differential equation.

indexback to summary
private int index

Index of the instance in the expandable set.

jacobianProvidersback to summary
private List<ParameterJacobianProvider> jacobianProviders

FODE with exact parameter Jacobian computation skill.

jodeback to summary
private MainStateJacobianProvider jode

FODE with exact primary Jacobian computation skill.

matricesDataback to summary
private double[] matricesData

State and parameters Jacobian matrices in a row.

paramDimback to summary
private int paramDim

Parameters dimension.

podeback to summary
private ParameterizedODE pode

FODE without exact parameter Jacobian computation skill.

selectedParametersback to summary
private ParameterConfiguration[] selectedParameters

Selected parameters for parameter Jacobian computation.

stateDimback to summary
private int stateDim

Main state vector dimension.

Constructor Detail

JacobianMatricesback to summary
public JacobianMatrices(final FirstOrderDifferentialEquations fode, final double[] hY, final 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:FirstOrderDifferentialEquations

the primary first order differential equations set to extend

hY:double[]

step used for finite difference computation with respect to state vector

parameters:String[]

parameters to consider for Jacobian matrices processing (may be null if parameters Jacobians is not desired)

Exceptions
DimensionMismatchException:
if there is a dimension mismatch between the steps array hY and the equation dimension
JacobianMatricesback to summary
public JacobianMatrices(final MainStateJacobianProvider jode, final 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:MainStateJacobianProvider

the primary first order differential equations set to extend

parameters:String[]

parameters to consider for Jacobian matrices processing (may be null if parameters Jacobians is not desired)

Method Detail

addParameterJacobianProviderback to summary
public void addParameterJacobianProvider(final ParameterJacobianProvider provider)

Add a parameter Jacobian provider.

Parameters
provider:ParameterJacobianProvider

the parameter Jacobian provider to compute exactly the parameter Jacobian matrix

checkDimensionback to summary
private void checkDimension(final int expected, final Object array) throws DimensionMismatchException

Check array dimensions.

Parameters
expected:int

expected dimension

array:Object

(may be null if expected is 0)

Exceptions
DimensionMismatchException:
if the array dimension does not match the expected one
getCurrentMainSetJacobianback to summary
public void getCurrentMainSetJacobian(final double[][] dYdY0)

Get the current value of the Jacobian matrix with respect to state.

Parameters
dYdY0:double[][]

current Jacobian matrix with respect to state.

getCurrentParameterJacobianback to summary
public void getCurrentParameterJacobian(String pName, final double[] dYdP)

Get the current value of the Jacobian matrix with respect to one parameter.

Parameters
pName:String

name of the parameter for the computed Jacobian matrix

dYdP:double[]

current Jacobian matrix with respect to the named parameter

registerVariationalEquationsback to summary
public void registerVariationalEquations(final ExpandableStatefulODE expandable) throws DimensionMismatchException, MismatchedEquations

Register the variational equations for the Jacobians matrices to the expandable set.

Parameters
expandable:ExpandableStatefulODE

expandable set into which variational equations should be registered

Exceptions
DimensionMismatchException:
if the dimension of the partial state does not match the selected equations set dimension
MismatchedEquations:
if the primary set of the expandable set does not match the one used to build the instance
See Also
ExpandableStatefulODE#addSecondaryEquations(SecondaryEquations)
setInitialMainStateJacobianback to summary
public void setInitialMainStateJacobian(final 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:double[][]

initial Jacobian matrix w.r.t. state

Exceptions
DimensionMismatchException:
if matrix dimensions are incorrect
setInitialParameterJacobianback to summary
public void setInitialParameterJacobian(final String pName, final 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:String

parameter name

dYdP:double[]

initial Jacobian column vector with respect to the parameter

Exceptions
UnknownParameterException:
if a parameter is not supported
DimensionMismatchException:
if the column vector does not match state dimension
setParameterizedODEback to summary
public void setParameterizedODE(final ParameterizedODE parameterizedOde)

Set a parameter Jacobian provider.

Parameters
parameterizedOde:ParameterizedODE

the parameterized ODE to compute the parameter Jacobian matrix using finite differences

setParameterStepback to summary
public void setParameterStep(final String parameter, final 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:String

parameter to consider for Jacobian processing

hP:double

step for Jacobian finite difference computation w.r.t. the specified parameter

Exceptions
UnknownParameterException:
if the parameter is not supported
See Also
ParameterizedODE
org.apache.commons.math3.ode back to summary

private Class JacobianMatrices.JacobiansSecondaryEquations

extends Object
implements SecondaryEquations
Class Inheritance
  • java.lang.Object
  • org.apache.commons.math3.ode.JacobianMatrices.JacobiansSecondaryEquations
All Implemented Interfaces
org.apache.commons.math3.ode.SecondaryEquations

Local implementation of secondary equations.

This class is an inner class to ensure proper scheduling of calls by forcing the use of JacobianMatrices#registerVariationalEquations(ExpandableStatefulODE).

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public void
computeDerivatives(final double
current value of the independent time variable
t
,
final double[]
array containing the current value of the primary state vector
y
,
final double[]
array containing the derivative of the primary state vector
yDot
,
final double[]
array containing the current value of the secondary state vector
z
,
final double[]
placeholder array where to put the derivative of the secondary state vector
zDot
)

Implements org.apache.commons.math3.ode.SecondaryEquations.computeDerivatives.

Compute the derivatives related to the secondary state parameters.

public int
getDimension()

Implements org.apache.commons.math3.ode.SecondaryEquations.getDimension.

Get the dimension of the secondary state parameters.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

JacobiansSecondaryEquationsback to summary
private JacobiansSecondaryEquations()

Method Detail

computeDerivativesback to summary
public void computeDerivatives(final double t, final double[] y, final double[] yDot, final double[] z, final double[] zDot) throws MaxCountExceededException, DimensionMismatchException

Implements org.apache.commons.math3.ode.SecondaryEquations.computeDerivatives.

Doc from org.apache.commons.math3.ode.SecondaryEquations.computeDerivatives.

Compute the derivatives related to the secondary state parameters.

Parameters
t:double

current value of the independent time variable

y:double[]

array containing the current value of the primary state vector

yDot:double[]

array containing the derivative of the primary state vector

z:double[]

array containing the current value of the secondary state vector

zDot:double[]

placeholder array where to put the derivative of the secondary state vector

Exceptions
MaxCountExceededException:
if the number of functions evaluations is exceeded
DimensionMismatchException:
if arrays dimensions do not match equations settings
getDimensionback to summary
public int getDimension()

Implements org.apache.commons.math3.ode.SecondaryEquations.getDimension.

Doc from org.apache.commons.math3.ode.SecondaryEquations.getDimension.

Get the dimension of the secondary state parameters.

Returns:int

dimension of the secondary state parameters

org.apache.commons.math3.ode back to summary

private Class JacobianMatrices.MainStateJacobianWrapper

extends Object
implements MainStateJacobianProvider
Class Inheritance
  • java.lang.Object
  • org.apache.commons.math3.ode.JacobianMatrices.MainStateJacobianWrapper
All Implemented Interfaces
org.apache.commons.math3.ode.MainStateJacobianProvider, org.apache.commons.math3.ode.FirstOrderDifferentialEquations

Wrapper class to compute jacobian matrices by finite differences for ODE which do not compute them by themselves.

Field Summary

Modifier and TypeField and Description
private final double[]
hY

Steps for finite difference computation of the jacobian df/dy w.r.t. state.

private final FirstOrderDifferentialEquations
ode

Raw ODE without jacobians computation skill to be wrapped into a MainStateJacobianProvider.

Constructor Summary

AccessConstructor and Description
pack-priv
MainStateJacobianWrapper(final FirstOrderDifferentialEquations
original ODE problem, without jacobians computation skill
ode
,
final double[]
step sizes to compute the jacobian df/dy
hY
)

Wrap a FirstOrderDifferentialEquations into a MainStateJacobianProvider.

Method Summary

Modifier and TypeMethod and Description
public void
computeDerivatives(double
current value of the independent time variable
t
,
double[]
array containing the current value of the state vector
y
,
double[]
placeholder array where to put the time derivative of the state vector
yDot
)

Implements org.apache.commons.math3.ode.FirstOrderDifferentialEquations.computeDerivatives.

Get the current time derivative of the state vector.

public void
computeMainStateJacobian(double
current value of the independent time variable
t
,
double[]
array containing the current value of the main state vector
y
,
double[]
array containing the current value of the time derivative of the main state vector
yDot
,
double[][]
placeholder array where to put the jacobian matrix of the ODE w.r.t. the main state vector
dFdY
)

Implements org.apache.commons.math3.ode.MainStateJacobianProvider.computeMainStateJacobian.

Compute the jacobian matrix of ODE with respect to main state.

public int
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

hYback to summary
private final double[] hY

Steps for finite difference computation of the jacobian df/dy w.r.t. state.

odeback to summary
private final FirstOrderDifferentialEquations ode

Raw ODE without jacobians computation skill to be wrapped into a MainStateJacobianProvider.

Constructor Detail

MainStateJacobianWrapperback to summary
pack-priv MainStateJacobianWrapper(final FirstOrderDifferentialEquations ode, final double[] hY) throws DimensionMismatchException

Wrap a FirstOrderDifferentialEquations into a MainStateJacobianProvider.

Parameters
ode:FirstOrderDifferentialEquations

original ODE problem, without jacobians computation skill

hY:double[]

step sizes to compute the jacobian df/dy

Exceptions
DimensionMismatchException:
if there is a dimension mismatch between the steps array hY and the equation dimension

Method Detail

computeDerivativesback to summary
public void computeDerivatives(double t, double[] y, double[] yDot) throws MaxCountExceededException, DimensionMismatchException

Implements org.apache.commons.math3.ode.FirstOrderDifferentialEquations.computeDerivatives.

Doc from org.apache.commons.math3.ode.FirstOrderDifferentialEquations.computeDerivatives.

Get the current time derivative of the state vector.

Parameters
t:double

current value of the independent time variable

y:double[]

array containing the current value of the state vector

yDot:double[]

placeholder array where to put the time derivative of the state vector

Exceptions
MaxCountExceededException:
if the number of functions evaluations is exceeded
DimensionMismatchException:
if arrays dimensions do not match equations settings
computeMainStateJacobianback to summary
public void computeMainStateJacobian(double t, double[] y, double[] yDot, double[][] dFdY) throws MaxCountExceededException, DimensionMismatchException

Implements org.apache.commons.math3.ode.MainStateJacobianProvider.computeMainStateJacobian.

Doc from org.apache.commons.math3.ode.MainStateJacobianProvider.computeMainStateJacobian.

Compute the jacobian matrix of ODE with respect to main state.

Parameters
t:double

current value of the independent time variable

y:double[]

array containing the current value of the main state vector

yDot:double[]

array containing the current value of the time derivative of the main state vector

dFdY:double[][]

placeholder array where to put the jacobian matrix of the ODE w.r.t. the main state vector

Exceptions
MaxCountExceededException:
if the number of functions evaluations is exceeded
DimensionMismatchException:
if arrays dimensions do not match equations settings
getDimensionback to summary
public int getDimension()

Implements org.apache.commons.math3.ode.FirstOrderDifferentialEquations.getDimension.

Doc from org.apache.commons.math3.ode.FirstOrderDifferentialEquations.getDimension.

Get the dimension of the problem.

Returns:int

dimension of the problem

org.apache.commons.math3.ode back to summary

public Class JacobianMatrices.MismatchedEquations

extends MathIllegalArgumentException
Class Inheritance

Special exception for equations mismatch.
Since
3.1

Field Summary

Modifier and TypeField and Description
private static final long

Constructor Summary

AccessConstructor and Description
public
MismatchedEquations()

Simple constructor.

Method Summary

Inherited from org.apache.commons.math3.exception.MathIllegalArgumentException:
getContextgetLocalizedMessagegetMessage

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Hides org.apache.commons.math3.exception.MathIllegalArgumentException.serialVersionUID.

Serializable UID.

Constructor Detail

MismatchedEquationsback to summary
public MismatchedEquations()

Simple constructor.