Choose Jacobian Method for Implicit Solvers

Implicit solvers, such as ode15s, compute the solver Jacobian as a step in the solver algorithm. The Solver Jacobian Method configuration parameter specifies the algorithm the solver uses to compute the solver Jacobian. The software provides perturbation and analytical methods that both have full and sparse options. Sparse methods and analytical methods can speed up simulations by reducing the number of calculations or computational complexity involved in computing the solver Jacobian.

By default, the Solver Jacobian method parameter value is auto, and the software chooses the solver Jacobian method. In most cases, the software chooses an appropriate Jacobian method for the model and solver.

For information about available implicit solvers, see Variable Step Solvers in Simulink.

What is the Solver Jacobian?

The solver Jacobian is a submatrix of the model Jacobian, which represents the continuous dynamics in the system of equations implemented by the model. The system of equations that represents the continuous dynamics in a model has this general form:

$$\begin{array}{l}\dot{x}=f(x,t,u)\\ y=g(x,t,u).\end{array}$$

where:

• x represents the system states.

• t is time.

• u represents the system inputs.

• y represents the system outputs.

• The function f computes the system state derivatives.

• The function g computes the system outputs.

The model Jacobian, J, for these systems of equations has the form:

$$J=\left(\begin{array}{cc}\frac{\partial f}{\partial x}& \frac{\partial f}{\partial u}\\ \frac{\partial g}{\partial x}& \frac{\partial g}{\partial u}\end{array}\right)=\left(\begin{array}{cc}A& B\\ C& D\end{array}\right).$$

where A, B, C, and D denote submatrices of the model Jacobian matrix.

Submatrix A represents the partial derivative of the function f that computes state derivatives with respect to the states x. This submatrix corresponds to the solver Jacobian $$J_x$$.

$$J_x=A=\frac{\partial f}{\partial x}.$$

Automatic Solver Jacobian Method Selection

When the Solver Jacobian method parameter value is auto, the software chooses the solver Jacobian method by analyzing the model and the selected solver. The software chooses an appropriate Jacobian method for most models.

The software selects a sparse method If:

• The model has more than 50 states.

• The solver is ode23s.

For details, see Full and Sparse Solver Jacobian Methods.

The software selects a perturbation method if the model contains any blocks that:

• Do not provide an analytical Jacobian.

• Provide an analytical Jacobian that is not appropriate for simulation.

For details, see Analytical Solver Jacobian Methods.

The image depicts the solver Jacobian selection algorithm.

Full and Sparse Solver Jacobian Methods

In many systems, the solver Jacobian is sparse. Sparse matrices contain many elements that are zero. The sparsity pattern refers to the pattern of zero and nonzero elements in a sparse matrix. The sparsity pattern is represented as an n-by-n matrix, where:

• n is the number of states in the system.

• Each column corresponds to a state.

• Each row corresponds to the equation that computes a state derivative.

An element in the sparsity pattern is a 1 if the state that corresponds to the column appears in the equation that corresponds to the row. For example, consider this system that has three states:

$$\begin{array}{l}{\dot{x}}_1=f_1(x_1,x_3)\\ {\dot{x}}_2=f_2(x_2)\\ {\dot{x}}_3=f_3(x_2).\end{array}$$

The sparsity pattern J_x,pattern of the solver Jacobian J_x is a 3-by-3 matrix.

$$J_{x,pattern}=\left(\begin{array}{ccc}1& 0& 1\\ 0& 1& 0\\ 0& 1& 0\end{array}\right)$$

By using the solver Jacobian sparsity pattern, sparse solver Jacobian methods can compute the solver Jacobian with fewer calculations than full methods. Because they perform fewer calculations, sparse Jacobian methods can speed up simulation execution. However, sparse methods might increase compilation time.

Sparse methods provide more benefit in systems that have many states and simulations that frequently compute the solver Jacobian. For example, a sparse method provides more benefit if you use ode23s because the solver computes the solver Jacobian in every time step.

For information about how to access and interpret the sparsity pattern in MATLAB^®, see Exploring the Solver Jacobian Structure of a Model.

• If you select sparse perturbation and your model contains data store blocks, Simulink^® applies the full perturbation method.

Analytical Solver Jacobian Methods

Analytical methods compute the solver Jacobian by solving analytical equations. Analytical methods can reduce computational complexity and speed up simulation execution. The sparse analytical method can provide additional benefit by using the sparsity pattern to reduce the number of analytical equations to solve.

Analytical methods are not supported in models that contain blocks that:

• Do not provide an analytical Jacobian.

• Provide an analytical Jacobian that is not appropriate for simulation.

  For example, the Saturation block provides a Jacobian that is appropriate for linearization but not for simulation if you enable the Treat as gain when linearizing parameter.

When you select the full or sparse analytical method, the software uses a perturbation method instead if the analytical method is not supported in the model.

The sparse analytical method is not supported in rapid accelerator simulations. If you select the sparse analytical method, the software uses the sparse perturbation method in rapid accelerator simulations.

The sparse analytical method uses UMFPACK for linear algebraic operations.

Solver Jacobian Perturbation Methods

Perturbation methods compute the solver Jacobian by following these steps for each state in the system:

1. Make a small change to the state value.

2. Compute state derivatives using the new state value

3. Compute partial derivative of state derivative functions with respect to the perturbed state

You can choose the full or sparse perturbation method.

• The full perturbation method solves the full set of perturbation equations, computing every element in the solver Jacobian matrix. The full perturbation method uses LAPACK for linear algebraic operations.

• The sparse perturbation method solves the perturbation equations only if the value of an element in the current solver Jacobian is nonzero. The sparse perturbation method uses UMFPACK for linear algebraic operations.

For example, consider the system that has three states.

$$\begin{array}{l}{\dot{x}}_1=f_1(x_1,x_3)\\ {\dot{x}}_2=f_2(x_2)\\ {\dot{x}}_3=f_3(x_2).\end{array}$$

The full perturbation method computes the solver Jacobian by solving the perturbation equations for every element of the matrix. In this system, the software perturbs each state one by one and computes three partial state derivatives for each state perturbation.

$$\begin{array}{c}{J}_x=\left(\begin{array}{ccc}\frac{\partial f_1}{\partial x_1}& \frac{\partial f_1}{\partial x_2}& \frac{\partial f_1}{\partial x_3}\\ \frac{\partial f_2}{\partial x_1}& \frac{\partial f_2}{\partial x_2}& \frac{\partial f_2}{\partial x_3}\\ \frac{\partial f_3}{\partial x_1}& \frac{\partial f_3}{\partial x_2}& \frac{\partial f_3}{\partial x_3}\end{array}\right)\\ =\left(\begin{array}{ccc}\frac{f_1(x_1+\Delta x_1,x_2,x_3)-f_1}{\Delta x_1}& \frac{f_1(x_1,x_2+\Delta x_2,x_3)-f_1}{\Delta x_2}& \frac{f_1(x_1,x_2,x_3+\Delta x_3)-f_1}{\Delta x_3}\\ \frac{f_2(x_1+\Delta x_1,x_2,x_3)-f_2}{\Delta x_1}& \frac{f_2(x_1,x_2+\Delta x_2,x_3)-f_2}{\Delta x_2}& \frac{f_2(x_1,x_2,x_3+\Delta x_3)-f_2}{\Delta x_3}\\ \frac{f_3(x_1+\Delta x_1,x_2,x_3)-f_3}{\Delta x_1}& \frac{f_3(x_1,x_2+\Delta x_2,x_3)-f_3}{\Delta x_2}& \frac{f_3(x_1,x_2,x_3+\Delta x_3)-f_3}{\Delta x_3}\end{array}\right)\end{array}$$

To determine which perturbation equations to solve and which states to perturb, the sparse perturbation method analyzes the sparsity pattern of the solver Jacobian. By perturbing the states x₁ and x₂ together, the sparse method perturbs the states x₁ and x₂ together and computes the solver Jacobian for this system as:

$$J_x=\left(\begin{array}{ccc}\frac{f_1(x_1+\Delta x_1,x_2+\Delta x_2,x_3)-f_1}{\Delta x_1}& 0& \frac{f_1(x_1,x_2,x_3+\Delta x_3)-f_1}{\Delta x_3}\\ 0& \frac{f_2(x_1+\Delta x_1,x_2+\Delta x_2,x_3)-f_2}{\Delta x_2}& 0\\ 0& \frac{f_3(x_1+\Delta x_1,x_2+\Delta x_2,x_3)-f_3}{\Delta x_2}& 0\end{array}\right)$$

The sparse perturbation method can speed up simulation execution for systems that have many continuous states. Even when the sparse perturbation method speeds up execution, it can increase compilation times. If the system does not have many states, the sparse perturbation method can even slow down simulation execution in some cases.