odeset
Create or modify options structure for ODE and PDE solvers
Syntax
Description
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=1e-3)
returns an options structure
with RelTol
set to 1e-3
.
modifies an existing options structure, options
= odeset(oldopts
,Name=Value
)oldopts
, using the newly
specified name-value arguments. 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.
Examples
Set and Update ODE Options
Create an options structure that contains values for RelTol
and AbsTol
.
options = odeset(RelTol=1e-8,AbsTol=1e-10);
Update the value of AbsTol
in the existing options structure.
options = odeset(options,AbsTol=1e-9)
options = struct with fields:
AbsTol: 1.0000e-09
BDF: []
Events: []
InitialStep: []
Jacobian: []
JConstant: []
JPattern: []
Mass: []
MassSingular: []
MaxOrder: []
MaxStep: []
MinStep: []
NonNegative: []
NormControl: []
OutputFcn: []
OutputSel: []
Refine: []
RelTol: 1.0000e-08
Stats: []
Vectorized: []
MStateDependence: []
MvPattern: []
InitialSlope: []
Combine Options Structures
Create two options structures.
opts_1 = odeset(RelTol=1e-8,AbsTol=1e-9,OutputFcn=@odeplot,Stats="on");
opts_2 = odeset(Mass=@(t) [t 0; 0 -t],MStateDependence="none",... MassSingular="no",OutputFc=@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.0000e-09
BDF: []
Events: []
InitialStep: []
Jacobian: []
JConstant: []
JPattern: []
Mass: @(t)[t,0;0,-t]
MassSingular: 'no'
MaxOrder: []
MaxStep: []
MinStep: []
NonNegative: []
NormControl: []
OutputFcn: @odephas2
OutputSel: []
Refine: []
RelTol: 1.0000e-08
Stats: 'on'
Vectorized: []
MStateDependence: 'none'
MvPattern: []
InitialSlope: []
Input Arguments
oldopts
— Old options structure
structure
Old options structure, specified as a structure previously created
using odeset
.
Data Types: struct
newopts
— New options structure
structure
New options structure, specified as a structure previously created
using odeset
.
Data Types: struct
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: options = odeset(AbsTol=1e-3,Reltol=1e-2,Jacobian=@J,Mass=M)
specifies thresholds for the absolute and relative error tolerances, a function that
returns the Jacobian matrix, and a numeric mass matrix.
RelTol
— Relative error tolerance
1e-3
(default) | positive scalar
Relative error tolerance, specified as 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=1e-5,AbsTol=1e-7)
Data Types: single
| double
AbsTol
— Absolute error tolerance
1e-6
(default) | positive scalar | vector
Absolute error tolerance, specified as 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=1e-5,AbsTol=1e-7)
Data Types: single
| double
NormControl
— Control error relative to norm
"off"
(default) | "on"
Control error relative to the norm of the solution, specified as "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 | vector
Nonnegative solution components, specified as 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 handle
Output function, specified as 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 built-in output functions that you can use with OutputFcn
:
Function Name | Description |
---|---|
odeplot | Plot all components of the solution vs. time |
odephas2 | 2-D phase plane plot of the first two solution components |
odephas3 | 3-D 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 function
vector of indices
Component selection for output function, specified as 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 factor
scalar
Solution refinement factor, specified as a scalar. The scalar specifies a factor by which the number of output points should increase in each step.
The default value of Refine
for most solvers is
1
, but ode45
uses a default
value of 4
, while ode78
and
ode89
use a default value of
8
. These solvers use a larger default value to
compensate for their tendency to take large steps.
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 inton
smaller intervals and returns solutions at each point.
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 "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
Implicit solvers display additional information about the solution:
The number of times that the partial derivatives matrix 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 size
scalar
Suggested initial step size, specified as 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=1e-3)
sets an upper bound of
1e-3
on the size of the initial
step.
MaxStep
— Maximum step size
0.1*abs(t0-tf)
(default) | scalar
Maximum step size, specified as 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 theRefine
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 ofRelTol
and use the solution to determine a suitable value forAbsTol
.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 reducingRelTol
andAbsTol
. UseMaxStep
only as a last resort in this case.
Example: opts = odeset(MaxStep=1e-2)
MinStep
— Minimum step size
scalar
Since R2024b
Minimum step size, specified as a positive scalar.
MinStep
sets a lower bound on the size of any
step taken by the solver. MinStep
must be less than
MaxStep
.
Solver steps are limited by floating-point precision regardless of the
value of MinStep
.
Example: opts = odeset(MinStep=1e-10)
Events
— Event function
function handle
Event function, specified as a function handle such as
@myEventsFcn
.
Function Signature
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 thei
th event function.isterminal(i) = 1
if the integration is to terminate at a zero of this event function. Otherwise, it is0
.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.
Events Output
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 inte
.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
.
Diagnostics
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.
Examples
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 zero-crossings of an oscillatory solution.
Data Types: function_handle
Jacobian
— Jacobian matrix
matrix | function handle | cell array
Jacobian matrix, specified as a matrix, cell array, or function that evaluates the Jacobian. The Jacobian is a matrix of partial derivatives of the function that defines the differential equations.
You can specify the Jacobian as a constant matrix with calculated values for , or as a function that computes the matrix elements and has the general form
dfdy = Fjac(t,y)
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 and . You can provide these matrices as a cell array of two
constant matrices , 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=@Fjac)
specifies the function
Fjac
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 pattern
sparse matrix | cell array
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 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 and .
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 array
Vectorized function toggle, specified as "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
element-wise operators that support vectorization.
For ode15i
only: Set the Vectorized
option using a two-element 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 matrix
matrix | function handle
Mass matrix, specified as a matrix or function handle. The ODE solvers can solve problems
containing a mass matrix of the form , where 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 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 , and avoiding the computation of the matrix inverse reduces the storage and execution time needed to solve the problem.
When 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 slopeyp0
such thatM(t0,y0)yp0 = f(t0,y0)
, whereyp0
is specified using theInitialSlope
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. Theode15s
andode23t
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 state-dependent (instead of constant) require the use of additional options:
For problems of the form , set the
MStateDependence
option to"none"
. This ensures that the solver calls the mass matrix function with a single input argument fort
.If the mass matrix depends on
y
, then setMStateDependence
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 state-dependent mass matrix , then set
MvPattern
to a sparse matrixS
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 "weak"
,
"strong"
, or "none"
.
For problems of the form , set the
MStateDependence
option to"none"
. This ensures that the solver calls the mass matrix function with a single input argument fort
.If the mass matrix depends on
y
, then setMStateDependence
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 pattern
sparse matrix
Mass matrix sparsity pattern, specified as a sparse matrix. Use this option to specify the
sparsity pattern of the matrix . The sparse matrix S
has
S(i,j) = 1
if for any k
, the
(i,k)
component of 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 "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 slope
vector of zeros (default) | vector
Consistent initial slope, specified as a vector. Use this option with the
ode15s
and ode23t
solvers
when solving DAEs. The specified vector is the initial slope such that . 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 formula
5
(default) | 4
| 3
| 2
| 1
Maximum order of formula, specified as 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 variable-order
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 "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
Output Arguments
options
— Options structure
structure
Options structure. options
can be used as
a fourth input argument to ode45
, ode23
, ode113
, ode15s
, ode23s
, ode23t
, ode23tb
,
or ode15i
.
Tips
See Summary of ODE Examples and Files for a list of ODE examples that illustrate the use of various options.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
All inputs must be constant.
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
Version History
Introduced before R2006aR2024b: Specify minimum step size
You can specify the minimum step size as a solver option by using the
MinStep
name-value argument.
MATLAB Command
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.
Select a Web Site
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: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)