matlab.ode.options.ODE15i Properties

Options for ODE15i solver

Since R2024b

expand all in page

matlab.ode.options.ODE15i objects are used with ode objects to specify options for the solution of ordinary differential equations. ode objects automatically populate the SolverOptions property with an options object specific to the selected solver, so you generally do not need to create matlab.ode.options.ODE15i objects explicitly.

Specify options for the ODE problem by changing property values of the matlab.ode.options.ODE15i object using dot notation. For example, if F is an ode object, then F.SolverOptions.OutputFcn = @odeplot specifies an output function that the solver calls after each successful time step.

Step Size

expand all

Suggested initial step size, specified as a positive scalar. InitialStep sets an upper bound on the size of the first step 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 of the integration. If the slope of all solution components is zero, then the solver might try a step size that is too large. If you know that the initial step size is too large, 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: F.SolverOptions.InitialStep = 1e-3, where F is an ode object, sets an upper bound of 1e-3 on the size of the initial step.

Maximum step size, specified as a positive scalar. MaxStep sets an upper bound on the size of any step that the solver takes. If the equation has periodic behavior, for example, then you can set MaxStep to a fraction of the period so that the solver does not step 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 of the solve method 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 RelativeTolerance and use the solution to determine a suitable value for AbsoluteTolerance.

  • 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 solve each separately. If you do not know the time at which the behavior occurs, try reducing RelativeTolerance and AbsoluteTolerance. Use MaxStep only as a last resort in this case.

Example: F.SolverOptions.MaxStep = 1e-2, where F is an ode object, sets an upper bound of 1e-2 on the step size.

Minimum step size, specified as a positive scalar. MinStep sets a lower bound on the size of any step that the solver takes. MinStep must be less than MaxStep.

Solver steps are limited by floating-point precision regardless of the value of MinStep.

Example: F.SolverOptions.MinStep = 1e-10, where F is an ode object, sets a lower limit of 1e-10 on the step size.

Error Control

expand all

Control error relative to the norm of the solution, specified as "off" or "on". If NormControl is "on", then the solver controls the error e at each step using the norm of the solution y rather than its absolute value:

norm(e(i)) <= max(RelativeTolerance*norm(y(i)),AbsoluteTolerance(i))

Example: F.SolverOptions.NormControl = "on", where F is an ode object, controls step error using the norm of the solution.

Solver Output

expand all

Output function, specified as a function handle. solve calls the output function after each successful time step. If you use solutionFcn to solve the ODE problem, then OutputFcn is ignored.

This table describes the built-in output functions that you can specify for OutputFcn.

Function NameDescription
odeplotPlot all components of the solution against time.
odephas2Create a 2-D phase plane plot of the first two solution components.
odephas3Create a 3-D phase plane plot of the first three solution components.
odeprintPrint the solution and time step to the Command Window.

If you write a custom output function, then it must use this function signature:

status = myOutputFcn(t,y,flag)

The output function you write must also respond appropriately to these flags.

FlagDescription
"init"

The solver calls myOutputFcn([tspan(1) tspan(end)],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 = myOutputFcn(t,y,[]) after each integration step for 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, then the ith column of y corresponds to the ith element of t.

  • If length(tspan) > 2, then the output is produced at every point in tspan.

  • If length(tspan) = 2, then the output is produced according to the Refine option of the solve method.

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

"done"

The solver calls myOutputFcn([],[],"done") once integration is complete to allow the output function to perform cleanup tasks.

Example: F.SolverOptions.OutputFcn = @odeplot, where F is an ode object, specifies odeplot as the output function that the solver calls after each successful time step.

Data Types: function_handle

Component selection for the output function, specified as a vector of indices. The vector specifies which components of the solution to pass to the output function. The number of solution components is equal to the number of elements in the vector output of the ODE function (which is stored in the ODEFcn property of the ode object).

Example: F.SolverOptions.OutputSelection = [1 3], where F is an ode object, passes the first and third components of the solution to the output function.

Other Properties

expand all

Vectorized function toggle, specified as "off", "on", or a 1-by-2 cell array of strings containing "off" and "on". Use this property to specify whether the ODE function accepts and returns vectors for the second and third arguments. That is, f(t,[y1 y2 y3 ...],[yp1 yp2 yp3 ...]) returns [f(t,y1,yp1) f(t,y2,yp2) f(t,y3,yp3) ...]. Specify this property as a string when the ODE function behaves the same for the second and third arguments. For example, set Vectorization to "on" when the ODE function accepts and returns vectors for the second and third arguments.

Compared to evaluating values one at a time, this vectorization reduces the number of function evaluations that the solver requires to compute all the columns of the Jacobian matrix and can significantly reduce solution time. See Array vs. Matrix Operations for a description of the element-wise operators that support vectorization.

Note

If you specify a constant Jacobian matrix using the Jacobian property of the ode object, then the solver ignores a value of "on" for Vectorization.

Example: F.SolverOptions.Vectorization = "on", where F is an ode object, specifies that the ODE function is vectorized.

Maximum order of formula, specified as an integer from 1 to 5. Use this property to specify the maximum order of the numerical differentiation formulas (NDFs) that the variable-order solver ode15i uses.

Example: F.SolverOptions.MaxOrder = 4, where F is an ode object, specifies a maximum order of 4 for the NDFs.

Compute consistent initial conditions when solving, specified as a numeric or logical 1 (true) or 0 (false). For more information, see decic.

Example: F.SolverOptions.ComputeConsistentInitialConditions = 0, where F is an ode object, disables computing consistent initial conditions when solving the ODE problem.

Version History

Introduced in R2024b

See Also

| | | |