odeJacobian

ODE Jacobian matrix

Since R2023b

Description

An odeJacobian object represents the Jacobian matrix for a system of ordinary differential equations. The Jacobian is a matrix of partial derivatives of the functions in the system of differential equations.

$$J=\frac{\partial f}{\partial y}=\left[\begin{array}{ccc}\frac{\partial f_1}{\partial y_1}& \frac{\partial f_1}{\partial y_2}& \cdots \\ \frac{\partial f_2}{\partial y_1}& \frac{\partial f_2}{\partial y_2}& \cdots \\ ⋮& ⋮& \end{array}\right]$$

Create an ode object to represent the ODE problem, and specify the odeJacobian object as the value of the Jacobian property to incorporate a Jacobian matrix or its sparsity pattern into the problem.

Creation

Syntax

J = odeJacobian

J = odeJacobian(Name=Value)

Description

J = odeJacobian creates an odeJacobian object with empty properties.

J = odeJacobian(Name=Value) specifies one or more property values using name-value arguments.

Properties

Jacobian — Jacobian matrix

matrix | function handle

Jacobian matrix, specified as a matrix or handle to a function that evaluates the Jacobian. The Jacobian is a matrix of partial derivatives of the functions that define the system of differential equations.

$$J=\frac{\partial f}{\partial y}=\left[\begin{array}{ccc}\frac{\partial f_1}{\partial y_1}& \frac{\partial f_1}{\partial y_2}& \cdots \\ \frac{\partial f_2}{\partial y_1}& \frac{\partial f_2}{\partial y_2}& \cdots \\ ⋮& ⋮& \end{array}\right]$$

For stiff ODE solvers (ode15s, ode23s, ode23t, and ode23tb), providing information about the Jacobian matrix is critical for reliability and efficiency. If you do not provide the Jacobian, then the ODE solver approximates it numerically using finite differences.

For large systems of equations where it is not feasible to provide the entire analytic Jacobian, use the SparsityPattern property to pass in the sparsity pattern of the Jacobian matrix. The solver uses the sparsity pattern to calculate a sparse Jacobian.

You can specify the value of the Jacobian property as:

• A constant matrix with calculated values for $$\frac{\partial f}{\partial y}$$.

• A handle to a function that computes the matrix elements and that accepts two input arguments, dfdy = Fjac(t,y). To give the function access to parameter values in the Parameters property, specify a third input argument in the function definition, dfdy = Fjac(t,y,p).

Example: J = odeJacobian(Jacobian=@Fjac) specifies the function Fjac that evaluates the Jacobian matrix.

Example: J = odeJacobian(Jacobian=[0 1; -2 1]) specifies a constant Jacobian matrix.

Data Types: single | double | function_handle

SparsityPattern — Jacobian sparsity pattern

sparse matrix

Jacobian sparsity pattern, specified as a sparse matrix. The sparse matrix contains 1s where there might be nonzero entries in the Jacobian. The ODE solver uses the sparsity pattern to generate a sparse Jacobian matrix numerically. Use this property to improve execution time when the ODE system is large, sparse, and you cannot provide an analytic Jacobian.

Note

If you specify a Jacobian matrix using the Jacobian property, then the solver ignores the SparsityPattern property.

Example: J = odeJacobian(SparsityPattern=S) specifies the Jacobian sparsity pattern using sparse matrix S.

Data Types: double

Examples

Specify Jacobian Matrix for Stiff ODE

The Van der Pol oscillator equation is a second-order differential equation. The equation includes a parameter $\mu$, and the equation becomes stiff when the value of $\mu$ is large.

$$\frac{d^{2}x}{d{t}^2}-\mu (1-x^2)\frac{dx}{dt}+x=0$$

Using the substitutions ${\mathit{y}}_1=\mathit{x}$ and ${\mathit{y}}_2=\frac{\mathrm{dx}}{\mathrm{dt}}$ produces a system of two first-order equations.

$$\begin{array}{l}\frac{d{y}_1}{dt}=y_2\\ \frac{d{y}_2}{dt}=\mu (1-y_1^2)y_2-y_1\end{array}$$

The Jacobian matrix for these equations is the matrix of partial derivatives of each equation with respect to both ${\mathit{y}}_1$ and ${\mathit{y}}_2$.

$$J=\left[\begin{array}{cc}\frac{\partial f_1}{\partial y_1}& \frac{\partial f_1}{\partial y_2}\\ \frac{\partial f_2}{\partial y_1}& \frac{\partial f_2}{\partial y_2}\end{array}\right]=\left[\begin{array}{cc}0& 1\\ -2\mu y_1{y}_2-1& \mu (1-y_1^2)\end{array}\right]$$

Solve the Van der Pol oscillator using $\mu =1000$ and initial values of [2; 0] by creating an ode object to represent the problem.

• Store the value of $\mu$ in the Parameters property.

• Specify the initial values in the InitialValue property.

• Specify the system of equations in the ODEFcn property, specifying three input arguments so that the value for $\mu$ is passed to the function.

• Specify a function that calculates the Jacobian matrix in the Jacobian property, specifying three input arguments so that the value for $\mu$ is passed to the function.

F = ode;
F.Parameters = 1000;
F.InitialValue = [2; 0];
F.ODEFcn = @(t,y,p) [y(2); p(1)*(1-y(1)^2)*y(2)-y(1)];
F.Jacobian = @(t,y,p) [0 1; -2*p(1)*y(1)*y(2)-1  p(1)*(1-y(1)^2)];

Display the ode object. The SelectedSolver property shows that the ode15s solver was automatically chosen for this problem.

F

F = 
  ode with properties:

   Problem definition
               ODEFcn: @(t,y,p)[y(2);p(1)*(1-y(1)^2)*y(2)-y(1)]
           Parameters: 1000
          InitialTime: 0
         InitialValue: [2x1 double]
             Jacobian: [1x1 odeJacobian]

   Solver properties
    AbsoluteTolerance: 1.0000e-06
    RelativeTolerance: 1.0000e-03
               Solver: auto
       SelectedSolver: ode15s

  Show all properties

Solve the system of equations over the time interval [0 3000] by using the solve method. Plot the first solution component.

S = solve(F,0,3000);
plot(S.Time,S.Solution(1,:),"-o")

Version History

Introduced in R2023b