# odeset

Create or alter options structure for ordinary differential equation solvers

## Syntax

`options = odeset('name1',value1,'name2',value2,...)options = odeset(oldopts,'name1',value1,...)options = odeset(oldopts,newopts)odeset`

## Description

The `odeset` function lets you adjust the integration parameters of the following ODE solvers.

For solving fully implicit differential equations:

`ode15i`

For solving initial value problems:

```ode23, ode45, ode113, ode15s, ode23s, ode23t, ode23tb```

See below for information about the integration parameters.

`options = odeset('name1',value1,'name2',value2,...)` creates an options structure that you can pass as an argument to any of the ODE solvers. In the resulting structure, `options`, the named properties have the specified values. For example, `'name1'` has the value `value1`. Any unspecified properties have default values. It is sufficient to type only the leading characters that uniquely identify a property name. Case is ignored for property names.

`options = odeset(oldopts,'name1',value1,...)` alters an existing options structure `oldopts`. This sets `options` equal to the existing structure `oldopts`, overwrites any values in `oldopts` that are respecified using name/value pairs, and adds any new pairs to the structure. The modified structure is returned as an output argument.

`options = odeset(oldopts,newopts)` alters an existing options structure `oldopts` by combining it with a new options structure `newopts`. Any new options not equal to the empty matrix overwrite corresponding options in `oldopts`.

`odeset` with no input arguments displays all property names as well as their possible and default values.

## ODE Properties

The following sections describe the properties that you can set using `odeset`. The available properties depend on the ODE solver you are using. There are several categories of properties:

 Note   This reference page describes the ODE properties for MATLAB®, Version 7. The Version 5 properties are supported only for backward compatibility. For information on the Version 5 properties, type at the MATLAB command line: `more on, type odeset, more off`.

## Error Control Properties

At each step, the solver estimates the local error `e` in the `i`th component of the solution. This error must be less than or equal to the acceptable error, which is a function of the specified relative tolerance, `RelTol`, and the specified absolute tolerance, `AbsTol`.

`|e(i)|`` max(RelTol*abs(y(i)),AbsTol(i))`

For routine problems, the ODE solvers deliver accuracy roughly equivalent to the accuracy you request. They deliver less accuracy for problems integrated over "long" intervals and problems that are moderately unstable. Difficult problems may require tighter tolerances than the default values. For relative accuracy, adjust `RelTol`. For the absolute error tolerance, the scaling of the solution components is important: if `|y|` is somewhat smaller than `AbsTol`, the solver is not constrained to obtain any correct digits in `y`. You might have to solve a problem more than once to discover the scale of solution components.

Roughly speaking, this means that you want `RelTol` correct digits in all solution components except those smaller than thresholds `AbsTol(i)`. Even if you are not interested in a component `y(i)` when it is small, you may have to specify `AbsTol(i)` small enough to get some correct digits in `y(i)` so that you can accurately compute more interesting components.

The following table describes the error control properties. Further information on each property is given following the table.

Property

Value

Description

`RelTol`

Positive scalar {`1e-3`}

Relative error tolerance that applies to all components of the solution vector `y`.

`AbsTol`

Positive scalar or vector {`1e-6`}

Absolute error tolerances that apply to the individual components of the solution vector.

`NormControl`

`on` | {`off`}

Control error relative to norm of solution.

### Description of Error Control Properties

`RelTol` — This tolerance is a measure of the error relative to the size of each solution component. Roughly, it controls the number of correct digits in all solution components, except those smaller than thresholds `AbsTol(i)`.

The default, `1e-3`, corresponds to 0.1% accuracy.

`AbsTol``AbsTol(i)` is a threshold below which the value of the `i`th solution component is unimportant. The absolute error tolerances determine the accuracy when the solution approaches zero.

If `AbsTol` is a vector, the length of `AbsTol` must be the same as the length of the solution vector `y`. If `AbsTol` is a scalar, the value applies to all components of `y`.

`NormControl` — Set this property `on` to request that the solvers control the error in each integration step with `norm(e) <= max(RelTol*norm(y),AbsTol)`. By default the solvers use a more stringent componentwise error control.

## Solver Output Properties

The following table lists the solver output properties that control the output that the solvers generate. Further information on each property is given following the table.

Property

Value

Description

`NonNegative`

Vector of integers

Specifies which components of the solution vector must be nonnegative. The default value is `[]`.

`OutputFcn`

Function handle

A function for the solver to call after every successful integration step.

`OutputSel`

Vector of indices

Specifies which components of the solution vector are to be passed to the output function.

`Refine`

Positive integer

Increases the number of output points by a factor of `Refine`.

`Stats`

`on` | {`off`}

Determines whether the solver should display statistics about its computations. By default, `Stats` is `off`.

### Description of Solver Output Properties

`NonNegative` — The `NonNegative` property is not available in `ode23s`, `ode15i`. In `ode15s`, `ode23t`, and `ode23tb`, `NonNegative` is not available for problems where there is a mass matrix.

`OutputFcn` — To specify an output function, set `'OutputFcn'` to a function handle. For example,

`options = odeset('OutputFcn',@myfun)`

sets `'OutputFcn'` to `@myfun`, a handle to the function `myfun`. See the `function_handle` reference page for more information.

The output function must be of the form

`status = myfun(t,y,flag)`

Parameterizing Functions explains how to provide additional parameters to `myfun`, if necessary.

The solver calls the specified output function with the following flags. Note that the syntax of the call differs with the flag. The function must respond appropriately:

Flag

Description

`init`

The solver calls `myfun(tspan,y0,'init')` before beginning the integration to allow the output function to initialize. `tspan` and `y0` are the input arguments to the ODE solver.

`{[]}`

The solver calls `status = myfun(t,y,[])` after each integration step on which output is requested. `t` contains points where output was generated during the step, and `y` is the numerical solution at the points in `t`. If `t` is a vector, the `i`th column of `y` corresponds to the `i`th element of `t`.

When `length(tspan) > 2` the output is produced at every point in `tspan`. When ```length(tspan) = 2``` the output is produced according to the `Refine` option.

`myfun` must return a `status` output value of `0` or `1`. If` status = 1`, the solver halts integration. You can use this mechanism, for instance, to implement a Stop button.

`done`

The solver calls `myfun([],[],'done')` when integration is complete to allow the output function to perform any cleanup chores.

You can use these general purpose output functions or you can edit them to create your own. Type `help function` at the command line for more information.

• `odeplot` — Time series plotting (default when you call the solver with no output arguments and you have not specified an output function)

• `odephas2` — Two-dimensional phase plane plotting

• `odephas3` — Three-dimensional phase plane plotting

• `odeprint` — Print solution as it is computed

 Note   If you call the solver with no output arguments, the solver does not allocate storage to hold the entire solution history.

`OutputSel` — Use `OutputSel` to specify which components of the solution vector you want passed to the output function. For example, if you want to use the `odeplot` output function, but you want to plot only the first and third components of the solution, you can do this using

```options = ... odeset('OutputFcn',@odeplot,'OutputSel',[1 3]);```

By default, the solver passes all components of the solution to the output function.

`Refine` — If `Refine` is `1`, the solver returns solutions only at the end of each time step. If `Refine` is `n` >`1`, the solver subdivides each time step into `n` smaller intervals and returns solutions at each time point. `Refine` does not apply when `length(tspan)>2` or the ODE solver returns the solution as a structure.

 Note   In all the solvers, the default value of `Refine` is `1`. Within `ode45`, however, the default is `4` to compensate for the solver's large step sizes. To override this and see only the time steps chosen by `ode45`, set `Refine` to `1`.

The extra values produced for `Refine` are computed by means of continuous extension formulas. These are specialized formulas used by the ODE solvers to obtain accurate solutions between computed time steps without significant increase in computation time.

`Stats` — By default, `Stats` is `off`. If it is `on`, after solving the problem the solver displays

• Number of successful steps

• Number of failed attempts

• Number of times the ODE function was called to evaluate f(t,y)

Solvers based on implicit methods, including `ode23s`, `ode23t`, `ode15s`, and `ode15i`, also display

• Number of times that the partial derivatives matrix ∂f/∂x was formed

• Number of LU decompositions

• Number of solutions of linear systems

## Step-Size Properties

The step-size properties specify the size of the first step the solver tries, potentially helping it to better recognize the scale of the problem. In addition, you can specify bounds on the sizes of subsequent time steps.

The following table describes the step-size properties. Further information on each property is given following the table.

Property

Value

Description

`InitialStep`

Positive scalar

Suggested initial step size.

`MaxStep`

Positive scalar {`0.1`*`abs(t0-tf)`}

Upper bound on solver step size.

### Description of Step-Size Properties

`InitialStep``InitialStep` sets an upper bound on the magnitude of the first step size the solver tries. If you do not set `InitialStep`, the initial step size is based on the slope of the solution at the initial time `tspan(1)`, and if the slope of all solution components is zero, the procedure might try a step size that is much too large. If you know this is happening or you want to be sure that the solver resolves important behavior at the start of the integration, help the code start by providing a suitable `InitialStep`.

`MaxStep` — If the differential equation has periodic coefficients or solutions, it might be a good idea to set `MaxStep` to some fraction (such as 1/4) of the period. This guarantees that the solver does not enlarge the time step too much and step over a period of interest. Do not reduce `MaxStep` for any of the following purposes:

• To produce more output points. This can significantly slow down solution time. Instead, use `Refine` to compute additional outputs by continuous extension at very low cost.

• When the solution does not appear to be accurate enough. Instead, reduce the relative error tolerance `RelTol`, and use the solution you just computed to determine appropriate values for the absolute error tolerance vector `AbsTol`. See Error Control Properties for a description of the error tolerance properties.

• To make sure that the solver doesn't step over some behavior that occurs only once during the simulation interval. If you know the time at which the change occurs, break the simulation interval into two pieces and call the solver twice. If you do not know the time at which the change occurs, try reducing the error tolerances `RelTol` and `AbsTol`. Use `MaxStep` as a last resort.

## Event Location Property

In some ODE problems the times of specific events are important, such as the time at which a ball hits the ground, or the time at which a spaceship returns to the earth. While solving a problem, the ODE solvers can detect such events by locating transitions to, from, or through zeros of user-defined functions.

The following table describes the `Events` property. Further information on each property is given following the table.

ODE Events Property

String

Value

Description

`Events`

Function handle

Handle to a function that includes one or more event functions.

### Description of Event Location Properties

`Events` — The function is of the form

`[value,isterminal,direction] = events(t,y)`

`value`, `isterminal`, and `direction` are vectors for which the `i`th element corresponds to the `i`th event function:

• `value(i)` is the value of the `i`th event function.

• `isterminal(i)` = `1` if the integration is to terminate at a zero of this event function, otherwise, `0`.

• `direction(i) = 0` if all zeros are to be located (the default), `+1` if only zeros where the event function is increasing, and `-1` if only zeros where the event function is decreasing.

If you specify an events function and events are detected, the solver returns three additional outputs:

• `A `column vector of times at which events occur

• Solution values corresponding to these times

• Indices into the vector returned by the events function. The values indicate which event the solver detected.

If you call the solver as

`[T,Y,TE,YE,IE] = solver(odefun,tspan,y0,options)`

the solver returns these outputs as `TE`, `YE`, and `IE` respectively. If you call the solver as

`sol = solver(odefun,tspan,y0,options)`

the solver returns these outputs as `sol.xe`, `sol.ye`, and `sol.ie`, respectively.

For examples that use an event function, see Event Location and Advanced Event Location in the MATLAB Mathematics documentation.

## Jacobian Matrix Properties

The stiff ODE solvers often execute faster if you provide additional information about the Jacobian matrix ∂f/∂y, a matrix of partial derivatives of the function that defines the differential equations.

$\frac{\partial f}{\partial y}=\left[\begin{array}{ccc}\frac{\partial {f}_{1}}{\partial {y}_{1}}& \frac{\partial {f}_{1}}{\partial {y}_{2}}& \dots \\ \frac{\partial {f}_{2}}{\partial {y}_{1}}& \frac{\partial {f}_{2}}{\partial {y}_{2}}& \dots \\ ⋮& ⋮& \end{array}\right]$

The Jacobian matrix properties pertain only to those solvers for stiff problems (`ode15s`, `ode23s`, `ode23t`, `ode23tb`, and `ode15i`) for which the Jacobian matrix ∂f/∂y can be critical to reliability and efficiency. If you do not provide a function to calculate the Jacobian, these solvers approximate the Jacobian numerically using finite differences. In this case, you might want to use the `Vectorized` or `JPattern` properties.

The following table describes the Jacobian matrix properties for all implicit solvers except `ode15i`. Further information on each property is given following the table. See Jacobian Properties for ode15i for `ode15i`-specific information.

Jacobian Properties for All Implicit Solvers Except ode15i

Property

Value

Description

`Jacobian`

Function handle | constant matrix

Matrix or function that evaluates the Jacobian.

`JPattern`

Sparse matrix of {0,1}

Generates a sparse Jacobian matrix numerically.

`Vectorized`

`on` | {`off`}

Allows the solver to reduce the number of function evaluations required.

### Description of Jacobian Properties

`Jacobian` — Supplying an analytical Jacobian often increases the speed and reliability of the solution for stiff problems. Set this property to a function `FJac`, where `FJac(t,y)` computes ∂f/∂y, or to the constant value of ∂f/∂y.

The Jacobian for the van der Pol Equation (Stiff), described in the MATLAB Mathematics documentation, can be coded as

```function J = vdp1000jac(t,y) J = [ 0 1 (-2000*y(1)*y(2)-1) (1000*(1-y(1)^2)) ];```

`JPattern``JPattern` is a sparsity pattern with `1`s where there might be nonzero entries in the Jacobian.

 Note   If you specify `Jacobian`, the solver ignores any setting for `JPattern`.

Set this property to a sparse matrix S with S(i,j) = 1 if component i of f(t,y) depends on component j of y, and 0 otherwise. The solver uses this sparsity pattern to generate a sparse Jacobian matrix numerically. If the Jacobian matrix is large and sparse, this can greatly accelerate execution. For an example using the `JPattern` property, see Example: Large, Stiff, Sparse Problem in the MATLAB Mathematics documentation.

`Vectorized` — The `Vectorized` property allows the solver to reduce the number of function evaluations required to compute all the columns of the Jacobian matrix, and might significantly reduce solution time.

Set `on` to inform the solver that you have coded the ODE function `F` so that ```F(t,[y1 y2 ...])``` returns `[F(t,y1) F(t,y2) ...]`. This allows the solver to reduce the number of function evaluations required to compute all the columns of the Jacobian matrix, and might significantly reduce solution time.

 Note   If you specify `Jacobian`, the solver ignores a setting of `'on'` for `'Vectorized'`.

With the MATLAB array notation, it is typically an easy matter to vectorize an ODE function. For example, you can vectorize the van der Pol Equation (Stiff), described in the MATLAB Mathematics documentation, by introducing colon notation into the subscripts and by using the array power (`.^`) and array multiplication (`.*`) operators.

```function dydt = vdp1000(t,y) dydt = [y(2,:); 1000*(1-y(1,:).^2).*y(2,:)-y(1,:)];```
 Note   Vectorization of the ODE function used by the ODE solvers differs from the vectorization used by the boundary value problem (BVP) solver, `bvp4c`. For the ODE solvers, the ODE function is vectorized only with respect to the second argument, while `bvp4c` requires vectorization with respect to the first and second arguments.

The following table describes the Jacobian matrix properties for `ode15i`.

Jacobian Properties for ode15i

Property

Value

Description

`Jacobian`

Function handle|Cell array of constant values

Function that evaluates the Jacobian or a cell array of constant values.

`JPattern`

Sparse matrices of {0,1}

Generates a sparse Jacobian matrix numerically.

`Vectorized`

`on` | {`off`}

Vectorized ODE function

### Description of Jacobian Properties for ode15i

`Jacobian` — Supplying an analytical Jacobian often increases the speed and reliability of the solution for stiff problems. Set this property to a function

`[dFdy,dFdp] = Fjac(t,y,yp)`

or to a cell array of constant values [∂F/∂y,(∂F/∂y)′].

`JPattern``JPattern` is a sparsity pattern with `1`'s where there might be nonzero entries in the Jacobian.

Set this property to `{dFdyPattern,dFdypPattern}`, the sparsity patterns of ∂F/∂y and ∂F/∂y′, respectively.

`Vectorized`

Set this property to `{yVect, ypVect}`. Setting `yVect` to `'on'` indicates that

`F(t, [y1 y2 ...], yp) `

returns

`[F(t,y1,yp), F(t,y2,yp) ...]`

Setting `ypVect` to `'on'` indicates that

`F(t,y,[yp1 yp2 ...])`

returns

`[F(t,y,yp1) F(t,y,yp2) ...]`

## Mass Matrix and DAE Properties

This section describes mass matrix and differential-algebraic equation (DAE) properties, which apply to all the solvers except `ode15i`. These properties are not applicable to `ode15i` and their settings do not affect its behavior.

The solvers of the ODE suite can solve ODEs of the form

 $M\left(t,y\right){y}^{\prime }=f\left(t,y\right)$ (1-3)

with a mass matrix M(t,y) that can be sparse.

When M(t,y) is nonsingular, the equation above is equivalent to y′ = M–1 f(t,y) and the ODE has a solution for any initial values y0 at t0. The more general form (Equation 1-3) is convenient when you express a model naturally in terms of a mass matrix. For large, sparse M(t,y), solving Equation 1-3 directly reduces the storage and run-time needed to solve the problem.

When M(t,y) is singular, then M(t,y) times M(t,y)y′ = f(t,y) is a DAE. A DAE has a solution only when y0 is consistent; that is, there exists an initial slope yp0 such that M(t0,y0)yp0 = f(t0,y0). If y0 and yp0 are not consistent, the solver treats them as guesses, attempts to compute consistent values that are close to the guesses, and continues to solve the problem. For DAEs of index 1, solving an initial value problem with consistent initial conditions is much like solving an ODE.

The `ode15s` and `ode23t` solvers can solve DAEs of index 1. For examples of DAE problems, see Example: Differential-Algebraic Problem, in the MATLAB Mathematics documentation, and the examples `amp1dae``amp1dae` and `hb1dae``hb1dae`.

The following table describes the mass matrix and DAE properties. Further information on each property is given following the table.

Mass Matrix and DAE Properties (Solvers Other Than ode15i)

Property

Value

Description

`Mass`

Matrix | function handle

Mass matrix or a function that evaluates the mass matrix M(t,y).

`MStateDependence`

```none | {weak} | strong```

Dependence of the mass matrix on y.

`MvPattern`

Sparse matrix

∂(M(t,y)v)/∂y sparsity pattern.

`MassSingular`

```yes | no | {maybe}```

Indicates whether the mass matrix is singular.

`InitialSlope`

Vector {zero vector}

Vector representing the consistent initial slope yp0.

### Description of Mass Matrix and DAE Properties

`Mass` — For problems of the form $M\left(t\right){y}^{\prime }=f\left(t,y\right)$, set `'Mass'` to a mass matrix M. For problems of the form $M\left(t\right){y}^{\prime }=f\left(t,y\right)$, set `'Mass'` to a function handle `@Mfun`, where `Mfun(t,y)` evaluates the mass matrix M(t,y). The `ode23s` solver can only solve problems with a constant mass matrix M. When solving DAEs, using `ode15s` or `ode23t`, it is advantageous to formulate the problem so that M is a diagonal matrix (a semiexplicit DAE).

For example problems, see Finite Element Discretization in the MATLAB Mathematics documentation, or the examples `fem2ode` or `batonode`.

`MStateDependence` — Set this property to `none` for problems $M\left(t\right){y}^{\prime }=f\left(t,y\right)$. Both `weak` and `strong` indicate M(t,y), but `weak` results in implicit solvers using approximations when solving algebraic equations.

`MvPattern` — Set this property to a sparse matrix S with S(i,j) = 1 if, for any k, the (i,k) component of M(t,y) depends on component j of y, and 0 otherwise. For use with the `ode15s`, `ode23t`, and `ode23tb` solvers when `MStateDependence` is `strong`. See `burgersode``burgersode` as an example.

`MassSingular` — Set this property to `no` if the mass matrix is not singular and you are using either the `ode15s` or `ode23t` solver. The default value of `maybe` causes the solver to test whether the problem is a DAE, by testing whether M(t0,y0) is singular.

`InitialSlope`Vector representing the consistent initial slope $y{p}_{0}$, where yp0 satisfies $M\left({t}_{0},{y}_{0}\right)\cdot y{p}_{0}=f\left({t}_{0},{y}_{0}\right)$. The default is the zero vector.

This property is for use with the `ode15s` and `ode23t` solvers when solving DAEs.

## ode15s and ode15i-Specific Properties

`ode15s` is a variable-order solver for stiff problems. It is based on the numerical differentiation formulas (NDFs). The NDFs are generally more efficient than the closely related family of backward differentiation formulas (BDFs), also known as Gear's methods. The `ode15s` properties let you choose among these formulas, as well as specifying the maximum order for the formula used.

`ode15i` solves fully implicit differential equations of the form

$f\left(t,y,{y}^{\prime }\right)=0$

using the variable order BDF method.

The following table describes the `ode15s` and `ode15i`-specific properties. Further information on each property is given following the table. Use `odeset` to set these properties.

ode15s and ode15i-Specific Properties

Property

Value

Description

`MaxOrder`

`1` | `2` | `3` | `4` | `{5}`

Maximum order formula used to compute the solution.

`BDF` (`ode15s` only)

`on` | `{off}`

Specifies whether you want to use the BDFs instead of the default NDFs.

### Description of ode15s and ode15i-Specific Properties

`MaxOrder` — Maximum order formula used to compute the solution.

`BDF` (`ode15s` only) — Set `BDF` `on` to have `ode15s` use the BDFs.

For both the NDFs and BDFs, the formulas of orders 1 and 2 are A-stable (the stability region includes the entire left half complex plane). The higher order formulas are not as stable, and the higher the order the worse the stability. There is a class of stiff problems (stiff oscillatory) that is solved more efficiently if `MaxOrder` is reduced (for example to `2`) so that only the most stable formulas are used.