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

example

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

## Properties

expand all

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`

Jacobian sparsity pattern, specified as a sparse matrix. The sparse matrix contains `1`s 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

collapse all

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 \left(1-{x}^{2}\right)\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 \left(1-{y}_{1}^{2}\right){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 \left(1-{y}_{1}^{2}\right)\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