Create or modify options structure for ODE and PDE solvers
creates an options structure that you can pass as an argument to ODE and PDE
solvers. In the structure, options
= odeset(Name,Value
,...)options
, the named options have the
specified values. Any unspecified options have default values. For example,
options = odeset('RelTol',1e3)
returns an options structure
with RelTol
set to 1e3
.
modifies
an existing options structure, options
= odeset(oldopts
,Name,Value
,...)oldopts
, using the
newly specified namevalue pairs. This overwrites any old values of
the specified options, and adds values for new options to the structure.
odeset
with no input arguments displays
all possible option names and their possible values. Default values
are indicated with {}
, where applicable.
Create an options structure that contains values for RelTol
and AbsTol
.
options = odeset('RelTol',1e8,'AbsTol',1e10);
Update the value of AbsTol
in the existing options structure.
options = odeset(options,'AbsTol',1e9)
options = struct with fields:
AbsTol: 1.0000e09
BDF: []
Events: []
InitialStep: []
Jacobian: []
JConstant: []
JPattern: []
Mass: []
MassSingular: []
MaxOrder: []
MaxStep: []
NonNegative: []
NormControl: []
OutputFcn: []
OutputSel: []
Refine: []
RelTol: 1.0000e08
Stats: []
Vectorized: []
MStateDependence: []
MvPattern: []
InitialSlope: []
Create two options structures.
opts_1 = odeset('RelTol',1e8,'AbsTol',1e9,'OutputFcn',@odeplot,'Stats','on');
opts_2 = odeset('Mass',@(t) [t 0; 0 t],'MStateDependence','none',... 'MassSingular','no','OutputFcn',@odephas2);
Combine the options structures, giving preference to opts_2
. Since both structures contain different values for OutputFcn
, the value in opts_2
overrides the one in opts_1
.
opts = odeset(opts_1,opts_2)
opts = struct with fields:
AbsTol: 1.0000e09
BDF: []
Events: []
InitialStep: []
Jacobian: []
JConstant: []
JPattern: []
Mass: @(t)[t,0;0,t]
MassSingular: 'no'
MaxOrder: []
MaxStep: []
NonNegative: []
NormControl: []
OutputFcn: @odephas2
OutputSel: []
Refine: []
RelTol: 1.0000e08
Stats: 'on'
Vectorized: []
MStateDependence: 'none'
MvPattern: []
InitialSlope: []
oldopts
— Old options structureOld options structure, specified as a structure previously created
using odeset
.
Data Types: struct
newopts
— New options structureNew options structure, specified as a structure previously created
using odeset
.
Data Types: struct
Specify optional
commaseparated pairs of Name,Value
arguments. Name
is
the argument name and Value
is the corresponding value.
Name
must appear inside quotes. You can specify several name and value
pair arguments in any order as
Name1,Value1,...,NameN,ValueN
.
options = odeset('AbsTol',1e3,'Reltol',1e2,'Jacobian',@J,'Mass',M)
specifies
thresholds for the absolute and relative error tolerances, a function
that returns the Jacobian, and a mass matrix.'RelTol'
— Relative error tolerance1e3
(default)  positive scalarRelative error tolerance, specified as the commaseparated pair
consisting of 'RelTol'
and a positive scalar. This
tolerance measures the error relative to the magnitude of each solution
component. Roughly speaking, it controls the number of correct digits
in all solution components, except those smaller than the absolute
tolerance AbsTol
.
At each step, the ODE solver estimates the local error e
in
the i
th component of the solution. To be successful,
the step must have acceptable error, as determined by both the relative
and absolute error tolerances:
e(i) <= max(RelTol*abs(y(i)),AbsTol(i))
Example: opts = odeset('RelTol',1e5,'AbsTol',1e7)
Data Types: single
 double
'AbsTol'
— Absolute error tolerance1e6
(default)  positive scalar  vectorAbsolute error tolerance, specified as the commaseparated pair
consisting of 'AbsTol'
and a positive scalar or
vector. This tolerance is a threshold below which the value of the
solution becomes unimportant. If the solution y
is
smaller than AbsTol
, then the solver does not need
to obtain any correct digits in y
. For this reason,
the value of AbsTol
should take into account the
scale of the solution components.
If AbsTol
is a vector, then it must be the
same length as the solution. If AbsTol
is a scalar,
then the value applies to all solution components.
At each step, the ODE solver estimates the local error e
in
the i
th component of the solution. To be successful,
the step must have acceptable error, as determined by both the relative
and absolute error tolerances:
e(i) <= max(RelTol*abs(y(i)),AbsTol(i))
Example: opts = odeset('RelTol',1e5,'AbsTol',1e7)
Data Types: single
 double
'NormControl'
— Control error relative to norm'off'
(default)  'on'
Control error relative to the norm of the solution, specified
as the commaseparated pair consisting of 'NormControl'
and 'on'
or 'off'
.
When NormControl
is 'on'
, the
solvers control the error e
at each step using
the norm of the solution rather than its absolute value:
norm(e(i)) <= max(RelTol*norm(y(i)),AbsTol(i))
Example: opts = odeset('NormControl','on')
Data Types: char
 string
'NonNegative'
— Nonnegative solution components[]
(default)  scalar  vectorNonnegative solution components, specified as the commaseparated
pair consisting of 'NonNegative'
and a scalar or
vector. The scalar or vector selects which solution components must
be nonnegative.
Note
NonNegative
is not available for ode23s
or ode15i
.
Additionally, for ode15s
, ode23t
,
and ode23tb
it is not available for problems
where there is a mass matrix.
Example: opts = odeset('NonNegative',1)
specifies
that the first solution component must be nonnegative.
Data Types: single
 double
'OutputFcn'
— Output function[]
or @odeplot
(default)  function handleOutput function, specified as the commaseparated pair consisting
of 'OutputFcn'
and a function handle. The ODE solver
calls the output function after each successful time step. If you
call an ODE solver with no outputs, then the output function defaults
to @odeplot
, which plots all of the solution components
as they are computed. Otherwise, the default is []
.
These are the builtin output functions that you can use with OutputFcn
:
Function Name  Description 

odeplot  Plot all components of the solution vs. time 
odephas2  2D phase plane plot of the first two solution components 
odephas3  3D phase plane plot of the first three solution components 
odeprint  Print solution and time step 
If you write a custom output function, then it must be of the form
status = myOutputFcn(t,y,flag)
The output function must also respond appropriately to these flags:
Flag  Description 

'init'  The solver calls 
[]  The solver calls

'done'  The solver calls 
Data Types: function_handle
'OutputSel'
— Component selection for output functionComponent selection for output function, specified as the commaseparated
pair consisting of 'OutputSel'
and a vector of
indices. The vector specifies which components of the solution to
pass to the output function.
Example: opts = odeset('OutputFcn',@myFcn,'OutputSel',[1
3])
passes the first and third components of the solution
to the output function.
'Refine'
— Solution refinement factor1
(most solvers) or 4
(ode45
only) (default)  scalarSolution refinement factor, specified as the commaseparated
pair consisting of 'Refine'
and a scalar. The scalar
specifies a factor by which the number of output points should increase
in each step.
If the refinement factor is 1
,
then the solver returns solutions only at the end of each step.
If the refinement factor is n>1
,
then the solver subdivides each step into n
smaller
intervals and returns solutions at each point.
The default value for most solvers is 1
,
but ode45
uses a default of 4
to
compensate for large step sizes.
The extra values produced by the refinement factor 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.
Note
Refine
does not apply when length(tspan)
> 2
, or when the ODE solver returns the solution as a
structure.
Example: opts = odeset('Refine',5)
increases
the number of output points by a factor of five.
'Stats'
— Solver statistics'off'
(default)  'on'
Solver statistics, specified as the commaseparated pair consisting
of 'Stats'
and 'on'
or 'off'
.
When 'on'
, the solver displays information after
completing the solution:
The number of successful steps
The number of failed attempts
The number of times the ODE function was called to evaluate $$f\left(t,y\right)$$
Implicit solvers display additional information about the solution:
The number of times that the partial derivatives matrix $$\partial f/\partial y$$ was formed
The number of LU decompositions
The number of solutions of linear systems
Example: opts = odeset('Stats','on')
Data Types: char
 string
'InitialStep'
— Suggested initial step sizeSuggested initial step size, specified as the commaseparated pair consisting of
'InitialStep'
and a positive scalar.
InitialStep
sets an upper bound on the magnitude
of the first step size that the solver tries.
If you do not specify an initial step size, then the solver
bases the initial step size on the slope of the solution at the initial
time point, tspan(1)
. If the slope of all solution
components is zero, then the solver might try a step size that is
too large. If you are aware that this is occurring, or if you want
to be sure that the solver resolves important behavior at the beginning
of the integration, then use InitialStep
to provide
a suitable initial step size.
Example: opts = odeset('InitialStep',1e3)
sets
an upper bound of 1e3
on the size of the initial
step.
'MaxStep'
— Maximum step size0.1*abs(t0tf)
(default)  scalarMaximum step size, specified as the commaseparated pair consisting of
'MaxStep'
and a positive scalar.
MaxStep
sets an upper bound on the size of any
step taken by the solver. If the equation has periodic behavior, for
example, then setting MaxStep
to a fraction of the
period ensures that the solver does not enlarge the step so much that it
steps over an area of interest.
Do not use MaxStep
just to obtain
more output points, as it can significantly slow down the integration.
Instead, use the Refine
option to compute additional
points at low computational cost.
Do not use MaxStep
to increase
the accuracy of the solution. If the solution is not accurate enough,
then reduce the value of RelTol
and use the solution
to determine a suitable value for AbsTol
.
Avoid using MaxStep
to make sure
the solver does not step over some behavior that occurs only once
in the integration interval. If you know the time at which the behavior
occurs, then break the interval into two pieces and call the solver
twice. If you do not know the time at which the change occurs, try
reducing RelTol
and AbsTol
.
Use MaxStep
only as a last resort in this case.
Example: opts = odeset('MaxStep',1e2)
'Events'
— Event functionEvent function, specified as the commaseparated pair consisting of
'Events'
and a function handle such as
@myEventsFcn
.
For ODEs: The event function specified by the function handle must have the general form
[value,isterminal,direction] = myEventsFcn(t,y)
For PDEs: The event function specified by the function handle must have the general form
[value,isterminal,direction] = myEventsFcn(m,t,xmesh,umesh)
In both cases, value
,
isterminal
, and direction
are vectors whose 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, it
is 0
.
direction(i) = 0
if all zeros are to be
located (the default). A value of +1
locates only zeros where the event function is increasing,
and 1
locates only zeros where the event
function is decreasing.
See Parameterizing Functions to see how to pass in additional inputs to the events function.
If you specify an events function, you can call the solver with three extra output arguments, such as
[t,y,te,ye,ie] = odeXY(odefun,tspan,y0,options)
The three additional outputs returned by the solver correspond to the detected events:
te
is a column vector of the times at
which events occurred.
ye
is the solution value corresponding
to the event times in te
.
ie
are indices into the vector returned
by the events function. The values indicate which event the
solver detected.
Alternatively, you can call the solver with a single output as
sol = odeXY(odefun,tspan,y0,options)
In this case, the event information is stored in the structure as
sol.te
, sol.ye
, and
sol.ie
.
The root finding mechanism employed by the ODE/PDE solver in conjunction with the event function has these limitations:
If a terminal event occurs during the first step of the integration, then the solver registers the event as nonterminal and continues integrating.
If more than one terminal event occurs during the first step, then only the first event registers and the solver continues integrating.
Zeros are determined by sign crossings between steps. Therefore, zeros with an even number of crossings between steps can be missed.
If the solver steps past events, try reducing
RelTol
and AbsTol
to
improve accuracy. Alternatively, set MaxStep
to
place an upper bound on the step size. Adjusting
tspan
does not change the steps taken by the
solver.
See ODE Event Location for examples of ODE event functions that detect the bounces of a ball and orbits of celestial bodies.
See Solve Oscillatory PDE with Event Logging for an example of a PDE event function detecting the zerocrossings of an oscillatory solution.
Data Types: function_handle
'Jacobian'
— Jacobian matrixJacobian matrix, specified as the commaseparated pair consisting
of 'Jacobian'
and a matrix or function that evaluates
the Jacobian. The Jacobian is a matrix of partial derivatives of the
function that defines the 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 \\ \vdots & \vdots & \end{array}\right]$$
For the stiff ODE solvers (ode15s
, ode23s
, ode23t
, ode23tb
, and ode15i
),
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 ode15i
only: The Jacobian
option
must specify matrices for both $$\frac{\partial f}{\partial y}$$ and $$\frac{\partial f}{\partial y\text{'}}$$.
You can provide these matrices as a cell array of two constant matrices $$\left\{\frac{\partial f}{\partial y},\text{\hspace{0.17em}}\text{\hspace{0.17em}}\frac{\partial f}{\partial y\text{'}}\right\}$$,
or as a function that computes the matrices and has the general form
[dfdy, dfdp] = Fjac(t,y,yp)
For very large systems where it is not feasible to provide the
entire analytic Jacobian, use the JPattern
property
to pass in the sparsity pattern of the Jacobian matrix. The solver
uses the sparsity pattern to calculate a sparse Jacobian.
Example: opts = odeset('Jacobian',@J)
specifies
the function J
that calculates the Jacobian matrix.
Example: opts = odeset('Jacobian',[0 1; 2 1])
specifies
a constant Jacobian matrix.
Example: opts
= odeset('Jacobian',{A,Ap})
specifies two constant Jacobian
matrices for use with ode15i
.
Data Types: single
 double
 cell
 function_handle
'JPattern'
— Jacobian sparsity patternJacobian sparsity pattern, specified as the commaseparated
pair consisting of 'JPattern'
and 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
option to improve execution time when the ODE system is large and
you cannot provide an analytic Jacobian.
For ode15i
only: Set
the JPattern
option using a cell array containing
two sparse matrices {dfdyPattern, dfdypPattern}
,
which are the sparsity patterns for $$\frac{\partial f}{\partial y}$$ and $$\frac{\partial f}{\partial y\text{'}}$$.
Note
If you specify a Jacobian matrix using Jacobian
,
then the solver ignores any setting for JPattern
.
Example: opts = odeset('JPattern',S)
specifies
the Jacobian sparsity pattern using sparse matrix S
.
Example: opts = odeset('JPattern',{dFdy, dFdyp})
specifies
two constant Jacobian sparsity patterns for use with ode15i
.
Data Types: double
 cell
'Vectorized'
— Vectorized function toggle'off'
(default)  'on'
 cell arrayVectorized function toggle, specified as the commaseparated pair consisting of
'Vectorized'
and either 'off'
or 'on'
. Use this option to inform the ODE solver
that the function is coded so that it accepts and returns vectors for
the second argument. That is, f(t,[y1 y2 y3...])
returns [f(t,y1) f(t,y2) f(t,y3) ...]
. Compared to
evaluating values one at a time, this vectorization 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. See Array vs. Matrix Operations for a description of the
elementwise operators that support vectorization.
For ode15i
only: Set
the Vectorized
option using a twoelement cell
array. Set the first element to 'on'
if f(t,[y1,y2,...],yp)
returns [f(t,y1,yp),
f(t,y2,yp), ...]
. Set the second element to 'on'
if f(t,y,[yp1,yp2,...])
returns [f(t,y,yp1),
f(t,y,yp2), ...]
. The default value of Vectorized
in
this case is {'off','off'}
.
Note
If you specify a Jacobian matrix using Jacobian
,
then the solver ignores a setting of 'on'
for Vectorized
.
Example: opts = odeset('JPattern',S,'Vectorized','on')
specifies
that the function is vectorized and sets the Jacobian sparsity pattern.
Example: opts = odeset('JPattern',{dy,dyp},'Vectorized',{'on','on'})
specifies
that the function is vectorized with respect to y
and yp
,
and also sets the Jacobian sparsity pattern for use with ode15i
.
Data Types: char
 cell
 string
ode15i
)'Mass'
— Mass matrixMass matrix, specified as the commaseparated pair consisting
of 'Mass'
and a matrix or function handle. The
ODE solvers can solve problems containing a mass matrix of the form $$M\left(t,y\right)\text{\hspace{0.17em}}y\text{'}=f\left(t,y\right)$$,
where $$M\left(t,y\right)$$ is
a mass matrix that can be full or sparse (the ode23s
solver
can solve only equations with constant mass matrices).
When the mass matrix is nonsingular, the equation simplifies to $$y\text{'}={M}^{1}\text{\hspace{0.17em}}f\left(t,y\right)$$ and the ODE has a solution for any initial value. However, it is often more convenient and natural to express the model in terms of the mass matrix directly using $$M\left(t,y\right)\text{\hspace{0.17em}}y\text{'}=f\left(t,y\right)$$, and avoiding the computation of the matrix inverse reduces the storage and execution time needed to solve the problem.
When $$M\left(t,y\right)$$ is
a singular matrix, then the problem is a system of differential algebraic
equations (DAEs). 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)
, where yp0
is
specified using the InitialSlope
option. DAEs are
characterized by their differential index, or the number of derivatives
required to simplify the system to an equivalent system of ODEs. 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. When solving DAEs, it is advantageous to
formulate the problem so that the mass matrix is a diagonal matrix
(a semiexplicit DAE).
In all cases, mass matrices that are time or statedependent (instead of constant) require the use of additional options:
For problems of the form $$M\left(t\right)y\text{'}=f\left(t,y\right)$$,
set the MStateDependence
option to 'none'
.
This ensures that the solver calls the mass matrix function with a
single input argument for t
.
If the mass matrix depends on y
,
then set MStateDependence
to either 'weak'
(default)
or 'strong'
. In both cases the solver calls the
mass matrix function with two inputs (t,y)
, but
the 'weak'
option results in implicit solvers using
approximations when solving algebraic equations.
If the system contains many equations with a strongly
statedependent mass matrix $$M\left(t,y\right)$$,
then set MvPattern
to a sparse matrix S
to
specify the sparsity pattern.
Example: The example files fem2ode
and batonode
illustrate
different uses of the mass matrix.
Data Types: single
 double
 function_handle
'MStateDependence'
— State dependence of mass matrix'weak'
(default)  'none'
 'strong'
State dependence of mass matrix, specified as the commaseparated
pair consisting of 'MStateDependence
and 'weak'
, 'strong'
,
or 'none'
.
For problems of the form $$M\left(t\right)y\text{'}=f\left(t,y\right)$$,
set the MStateDependence
option to 'none'
.
This ensures that the solver calls the mass matrix function with a
single input argument for t
.
If the mass matrix depends on y
,
then set MStateDependence
to either 'weak'
(default)
or 'strong'
. In both cases the solver calls the
mass matrix function with two inputs (t,y)
, but
the 'weak'
option results in implicit solvers using
approximations when solving algebraic equations.
Example: opts = odeset('Mass',@M,'MStateDependence','none')
specifies
that the mass matrix M
depends only on t
.
Data Types: char
 string
'MvPattern'
— Mass matrix sparsity patternMass matrix sparsity pattern, specified as the commaseparated
pair consisting of 'MvPattern'
and a sparse matrix.
Use this option to specify the sparsity pattern of the matrix $$\frac{\partial}{\partial y}\left[M\left(t,y\right)v\right]$$.
The sparse matrix S
has S(i,j) = 1
if
for any k
, the (i,k)
component
of $$M\left(t,y\right)$$ depends
on component j
of y
.
Note
MvPattern
is for use by ode15s
, ode23t
,
and ode23tb
when MStateDependence
is 'strong'
.
Example: opts = odeset('MStateDependence','strong','MvPattern',S)
'MassSingular'
— Singular mass matrix toggle'maybe'
(default)  'yes'
 'no'
Singular mass matrix toggle, specified as the commaseparated
pair consisting of 'MassSingular'
and 'maybe'
, 'yes'
,
or 'no'
. The default value of 'maybe'
causes
the solver to test whether the problem is a DAE, by testing whether
the mass matrix is singular. Avoid this check by specifying 'yes'
if
you know the system is a DAE, or 'no'
if it is
not.
Data Types: char
 string
'InitialSlope'
— Consistent initial slopeConsistent initial slope, specified as the commaseparated pair
consisting of 'InitialSlope'
and a vector. Use
this option with the ode15s
and ode23t
solvers
when solving DAEs. The specified vector is the initial slope $$y{\text{'}}_{0}$$ such
that $$M\left({t}_{0},{y}_{0}\right)y{\text{'}}_{0}=f\left({t}_{0},{y}_{0}\right)$$.
If the specified initial conditions are not consistent, then the solver
treats them as guesses, attempts to compute consistent values that
are close to the guesses, and continues to solve the problem.
Data Types: single
 double
ode15s
and ode15i
'MaxOrder'
— Maximum order of formula5
(default)  4
 3
 2
 1
Maximum order of formula, specified as the commaseparated pair
consisting of 'MaxOrder'
and an integer between 1
and 5
.
Use this option to specify the maximum order used in the numerical
differentiation formulas (NDFs) or backward differentiation formulas
(BDFs) that are used by the variableorder solvers ode15s
and ode15i
.
'BDF'
— Toggle to use BDFs with ode15s
'off'
(default)  'on'
Toggle to use backward differentiation formulas (BDFs) with ode15s
,
specified as the commaseparated pair consisting of 'BDF'
and
either 'off'
or 'on'
. The default
numerical differentiation formulas (NDFs) are generally more efficient
than BDFs, but the two are closely related.
Example: opts = odeset('BDF','on','MaxOrder',4)
enables
the use of BDFs by ode15s
with a maximum order
of 4
.
Data Types: char
 string
options
— Options structureOptions structure. options
can be used as
a fourth input argument to ode45
, ode23
, ode113
, ode15s
, ode23s
, ode23t
, ode23tb
,
or ode15i
.
See Summary of ODE Examples and Files for a list of ODE examples that illustrate the use of various options.
Usage notes and limitations:
All inputs must be constant.
You have a modified version of this example. Do you want to open this example with your edits?
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.