Create or alter options structure for ordinary differential equation solvers
options = odeset('name1',value1,'name2',value2,...)
options = odeset(oldopts,'name1',value1,...)
options = odeset(oldopts,newopts)
odeset
The odeset
function lets you adjust the
integration parameters of the following ODE solvers.
For solving fully implicit differential equations:
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.
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: 
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.
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, 1e3
, 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.
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.
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 Create Function Handle 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 

 The solver calls 
 The solver calls When

 The solver calls 
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)
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 
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
The stepsize 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 stepsize properties. Further information on each property is given following the table.
Property  Value  Description 

 Positive scalar  
 Positive scalar { 
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.
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 userdefined functions.
The following table describes the Events
property.
Further information on each property is given following the table.
ODE Events Property
String  Value  Description 

 Function handle  Handle to a function that includes one or more event functions. 
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.
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 \\ \vdots & \vdots & \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
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*(1y(1)^2)) ];
JPattern
— JPattern
is
a sparsity pattern with 1
s where there might be
nonzero entries in the Jacobian.
Note
If you specify 
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 
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*(1y(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, 
The following table describes the Jacobian matrix properties
for ode15i
.
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) ...]
This section describes mass matrix and differentialalgebraic
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(t,y){y}^{\prime}=f(t,y)$$  (13) 
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 y_{0} at t_{0}. The more general form (Equation 13) is convenient when you express a model naturally in terms of a mass matrix. For large, sparse M(t,y), solving Equation 13 directly reduces the storage and runtime 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 y_{0} is consistent; that is, there exists an initial slope yp_{0} such that M(t_{0},y_{0})yp_{0} = f(t_{0},y_{0}). If y_{0} and yp_{0} 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: DifferentialAlgebraic
Problem, in the MATLAB Mathematics documentation, and
the examples amp1dae
and 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)
Mass
— For problems of
the form $$M(t){y}^{\prime}=f(t,y)$$, set 'Mass'
to
a mass matrix M. For problems of the form $$M(t){y}^{\prime}=f(t,y)$$, 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(t){y}^{\prime}=f(t,y)$$. 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
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(t_{0},y_{0})
is singular.
InitialSlope
— Vector representing the consistent initial slope $$y{p}_{0}$$, where yp_{0} satisfies $$M({t}_{0},{y}_{0})\cdot y{p}_{0}=f({t}_{0},{y}_{0})$$. The default is the zero vector.
This property is for use with the ode15s
and ode23t
solvers when solving DAEs.
ode15s
is a variableorder
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(t,y,{y}^{\prime})=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 ode15iSpecific Properties
Property  Value  Description 


 Maximum order formula used to compute the solution. 

 Specifies whether you want to use the BDFs instead of the default NDFs. 
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
Astable (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.