matlab.ode.options.ODE23S Properties

Options for ODE23S solver

Since R2023b

matlab.ode.options.ODE23S 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.ODE23S objects explicitly.

Specify options for the ODE problem by changing property values of the matlab.ode.options.ODE23S 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

InitialStep — Suggested initial step size

positive scalar

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.

MaxStep — Maximum step size

0.1*abs(t0-tf) (default) | positive scalar

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 change 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 a limit of 1e-2 on the step size.

Error Control

NormControl — Control error relative to norm

"off" (default) | "on"

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

OutputFcn — Output function

[] (default) | function handle

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 use with OutputFcn.

Function Name	Description
odeplot	Plot all components of the solution against time.
odephas2	Create 2-D phase plane plot of the first two solution components.
odephas3	Create 3-D phase plane plot of the first three solution components.
odeprint	Print solution and time step to 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.

Flag	Description
"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

OutputSelection — Component selection for the output function

vector of indices

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

Vectorization — Vectorized function toggle

"off" (default) | "on"

Vectorized function toggle, specified as "off" or "on". Use this property to specify whether the ODE function 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 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 setting of "on" for Vectorized.

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

Version History

Introduced in R2023b