Simulink.Solver.VariableStepSolver Class

R2026b

Namespace: Simulink.Solver

Write variable-step plugin solver for Simulink simulation

Since R2026b

Description

Simulink.Solver.VariableStepSolver is the base class for authoring variable-step plugin solvers. Simulink^® provides several built-in solvers that can simulate a wide range of systems. However, the built-in solver integration algorithms are not necessarily ideal for all domains and problems. Using the plugin solver interface, you can implement custom solver integration algorithms for Simulink simulations.

At each time step in the simulation, a variable-step solver:

• Integrates continuous states by solving an initial value problem (IVP).

  In the first time step, the initial state defines the initial value for the IVP. The solver computes the state at the next time step, which becomes the initial value in the next time step.

• Advances time by determining a step size that satisfies specified error tolerances and the maximum step size determined by the simulator.

  The simulator determines the maximum step size based on the value of the Max step size configuration parameter and sample times in the simulated system. To ensure that the solver does not step past a hit time for a sample time in the model, the simulator might choose a maximum step size that is smaller than the value of the Max step size parameter.

To write a plugin solver, you define only the integration algorithm in the step method. The Simulink environment provides solver services, such as zero-crossing detection. For more information about Simulink solvers, see Choose a Solver.

To simulate a system using a plugin solver:

1. Save the class definition for the plugin solver in a location on the MATLAB^® path or add the plugin solver location to the path.

2. Register the plugin solver using the Simulink.Solver.register function.

3. Specify the Solver parameter as the name of the plugin solver.

To implement a fixed-step plugin solver, use the Simulink.Solver.FixedStepSolver class.

The Simulink.Solver.VariableStepSolver class is a handle class.

Class Attributes

Abstract

true

For information on class attributes, see Class Attributes.

Properties

NumStates — Number of continuous states in simulated system

positive scalar integer

Number of continuous states in simulated system, returned as a scalar integer. This property is available only during simulation.

The number of states in the simulated system determines the size of the state and state derivative input and output arguments for the step, forcingFunction, Jacobian, massMatrix, interpolateState, and reset methods.

Attributes:

GetAccess	public
SetAccess	private
Dependent	true

Data Types: double

AbsoluteTolerance — Absolute tolerance used to determine solver error in state computations

-Inf | positive scalar number

Absolute tolerance used to determine solver error in state computations, returned as a positive scalar number. The Absolute tolerance configuration parameter of the simulated system determines the property value. For the default parameter value, auto, the property value is -Inf.

Attributes:

GetAccess	public
SetAccess	private
Dependent	true

Data Types: double

RelativeTolerance — Relative tolerance used to determine solver error in state computations

-Inf | positive scalar number

Relative tolerance used to determine solver error in state computations, returned as a positive scalar number. The Relative tolerance configuration parameter of the simulated system defines the property value. By default, the parameter value is 1e-3. If the parameter value is auto, the property value is -Inf.

Attributes:

GetAccess	public
SetAccess	private
Dependent	true

Data Types: double

MaxStep — Maximum step size

positive scalar number

Maximum step size, returned as a positive scalar number. The Max step size configuration parameter of the simulated system defines the property value. If the parameter has the default value 'auto', the property value is -Inf.

Attributes:

GetAccess	public
SetAccess	private
Dependent	true

Data Types: double

MinStep — Minimum step size

positive scalar number

Minimum step size, returned as a positive scalar number. The Min step size configuration parameter of the simulated system defines the property value. If the parameter has the default value 'auto', the property value is -Inf.

Attributes:

GetAccess	public
SetAccess	private
Dependent	true

Data Types: double

InitialStepSize — Initial step size

positive scalar number

Initial step size for the simulation, returned as a positive scalar number. The Initial step size configuration parameter of the simulated system defines the property value. If the parameter has the default value auto, the property value is -Inf.

Attributes:

GetAccess	public
SetAccess	private
Dependent	true

Data Types: double

Methods

Public Methods

step	[tnext,xout] = step(slvr,t0,x0,tnextMax) Integrate continuous states to next time step. The step method is abstract. The implementation defines the plugin solver integration algorithm. To compute continuous states in the simulated system, the simulation calls the step method in each time step. Input arguments: slvr — Plugin solver instance t0 — Simulation time for current time step x0 — Continuous state values in current time step tnextMax — Maximum size of next step determined by simulator Output arguments: tnext — Simulation time of next time step xout — Continuous state values computed for next time step
forcingFunction	f = forcingFunction(slvr,t,x) Evaluate forcing function. To evaluate derivatives of continuous states in the simulated system, call this method in the implementation of the step method. The forcingFunction method is sealed. Input arguments: slvr — Plugin solver instance t — Time at which to evaluate continuous state derivatives x — Continuous state values at time t The forcingFunction method returns the right-hand side of the forcing function equation $$M(t,x)*\dot{x}=f(t,x),$$ where: M(t,x) is the mass matrix evaluated at time t with state values x. $$\dot{x}$$ is a vector of the continuous state derivatives. f(t,x) is the forcing function evaluated at time t with state values x. If the system is explicit, the mass matrix is an identity matrix and the method returns the continuous state derivatives.
Jacobian	J = Jacobian(slvr,t,x) Evaluate Jacobian of simulated system. If the integration algorithm requires the system Jacobian, call this method in the implementation of the step method. The Jacobian method is sealed. Input arguments: slvr — Plugin solver instance t — Time at which to evaluate Jacobian x — Continuous state values at time t The Jacobian method returns the system Jacobian matrix J, evaluated at time t with continuous state values x. To enable support for this method, the getProperties method must specify Jacobian as true.
massMatrix	M = massMatrix(slvr,t,x) Evaluate mass Matrix of simulated system. If the integration method uses the mass matrix, call this method in the implementation of the step method. The massMatrix method is sealed. Input arguments: slvr — Plugin solver instance t — Time at which to evaluate mass matrix x — Continuous state values at time t The massMatrix method returns the mass matrix M, evaluated at time t with state values x. The requirements for evaluating the mass matrix in the integration algorithm depend on the nature of the mass matrix in the simulated system. For example, if the mass matrix is constant, the solver can evaluate the mass matrix once, at the start of the simulation. To speed up solver execution during simulation, evaluate the mass matrix only when necessary. To enable support for this method, the getProperties method must specify MassMatrix as true.
isStateDependentMassMatrix	tf = isStateDependentMassMatrix(slvr) Returns true if the mass matrix of the simulated system depends on both time and state. To enable support for this method, specify MassMatrix as true in the getProperties method.
isTimeDependentMassMatrix	tf = isTimeDependentMassMatrix(slvr) Returns true if the mass matrix of the simulated system depends only on time. To enable support for this method, specify MassMatrix as true in the getProperties method.
isConstantMassMatrix	tf = isConstantMassMatrix(slvr) Returns true if the mass matrix of the simulated system is constant. To enable support for this method, specify MassMatrix as true in the getProperties method.
isIdentityMassMatrix	tf = isIdentityMassMatrix(slvr) Returns true if the mass matrix of the simulated system is the identity matrix. To enable support for this method, specify MassMatrix as true in the getProperties method.
interpolateState	xi = interpolateState(slvr,ti,tleft,tright,xleft,xright) Approximate continuous state values between time steps. Some solver services interpolate continuous state values between time steps. For example, the zero-crossing detection algorithm interpolates continuous states when locating the time of a zero crossing. By default, the interpolateState method provides a linear interpolation algorithm. To provide a more sophisticated interpolation scheme, implement this method. Input arguments: slvr — Plugin solver instance ti — Time at which to interpolate state values tleft — Time with known state values prior to ti tright — Time with known state values after ti xleft — State values at time tleft xright — State values at time xleft The interpolateState vector returns the interpolated state values as the vector xi.
getProperties	props = getProperties(slvr) Define properties of plugin solver. The getProperties method provides information about the plugin solver to the Simulink environment. The method returns the solver properties as the structure props. The structure contains these fields: MassMatrix — Mass matrix requirement, specified as true or false DAE — Differential-algebraic equation support, specified as true or false Jacobian — Solver Jacobian requirement, specified as true or false description — Description of plugin solver By default, the getProperties method specifies all solver properties as false.
start	start(slvr) Initialize solver. At the start of a simulation, the simulator initializes the solver by calling this method. Implement this method if the solver has unique requirements for initializing states or data structures. The simulator calls the start method only in the first simulation run after enabling fast restart. To reinitialize the solver between simulations, implement the stop method.
stop	stop(slvr) Reinitialize solver between fast restart simulations. The simulator calls this method at the end of each fast restart simulation. Implement this method if you implement the start method.
reset	reset(slvr,t0,x0,dx0) Reinitialize solver when solver reset occurs during simulation. The simulator resets the solver when solver events, such as zero-crossing events, occur during simulation. To reset information stored in the solver, such as cached derivative evaluations or state history, implement this method. Input arguments: slvr — Instance of plugin solver t0 — Time of solver reset x0 — Continuous state values at t0 dx0 — Continuous state derivatives at t0

Examples

Implement Variable-Step ODE12 Solver

The class ODE12 defines the integration algorithm for a variable-step ODE12 solver.

To speed up solver execution during simulation, the class defines properties to store the initial step size, maximum step size, minimum step size, absolute tolerance, and relative tolerance specified in the simulated system. The solver calls into Simulink by querying the base class property only once in the start method.

To determine an initial guess for the step size in the current time step, the solver uses the step size from the prior time step. To store the step size, the class defines the property StepSize. The start method initializes the property by querying the initial step size from the simulated system. If the simulated system specifies the initial step size as auto, the solver assigns a value of 1e-2. When the simulation resets the solver, the reset method resets the step size to the initial step size.

The step method implements the integration algorithm, which computes the first and second order state approximations by calling the forcingFunction method. The algorithm iteratively approximates the state values until the error for all the state values falls within the specified tolerance.

classdef ODE12 < Simulink.Solver.VariableStepSolver

properties
        InitStepSize
        MaxStepSize
        MinStepSize
        StepSize
        AbsTol
        RelTol
    end

    methods
        function start(slvr)
            slvr.MaxStepSize = slvr.MaxStep;
            slvr.MinStepSize = slvr.MinStep;
            slvr.AbsTol = slvr.AbsoluteTolerance;
            slvr.RelTol = slvr.RelativeTolerance;
            slvr.InitStepSize = slvr.InitialStepSize;

            if ~isfinite(slvr.InitStepSize)
                slvr.InitStepSize = 1e-2;
                slvr.StepSize = 1e-2;
            else
                slvr.StepSize = slvr.InitStepSize;
            end
        end

        function [tnext, xnext] = step(slvr,t0,x0,tmax)
            slvr.StepSize = min(slvr.StepSize,tmax - t0);

            f0 = slvr.forcingFunction(t0,x0);

            n = 1;
            while true
                t1 = t0 + slvr.StepSize;

                x1first = x0 + slvr.StepSize * f0;
                f1 = slvr.forcingFunction(t1,x1first);
                x1second = x0 + 0.5 * slvr.StepSize * (f0 + f1);

                if ~all(isfinite(x1second))
                    error("Plugin solver ODE12 received or computed nonfinite state values during integration.")
                end

                Ek = abs(x1second - x1first);
                tol = max(slvr.AbsTol, slvr.RelTol * abs(x1second));

                if all(Ek < tol)
                    break;
                else
                    if slvr.StepSize == slvr.MinStepSize
                        error("ODE12 did not converge. Consider decreasing the specified minimum step size.")
                    end
                    slvr.StepSize = 0.5 * slvr.StepSize;
                    slvr.StepSize = max(slvr.StepSize,slvr.MinStepSize);
                end
                n = n + 1;
            end

            xnext = x1second;
            tnext = t1;

            if n == 1
                slvr.StepSize = min(slvr.StepSize * 3,slvr.MaxStepSize);
            end
        end

        function reset(slvr,~,~,~)
            if ~isfinite(slvr.InitStepSize)
                slvr.StepSize = 1e-2;
            else
                slvr.StepSize = slvr.InitStepSize;
            end
        end
    end

end

To simulate a system using the plugin solver, register the solver. Then, specify the SolverType and Solver configuration parameters in the system. For example, this code registers the plugin solver ODE12 and then uses the solver to simulate the system MyModel.

Simulink.Solver.register("ODE12")
mdl = "MyModel";
set_param(mdl,SolverType="Variable-step")
set_param(mdl,Solver="ODE12")
out = sim(mdl);

Limitations

Plugin solvers do not support:

• Rapid accelerator simulation

• Software-in-the-loop (SIL) and processor-in-the-loop (PIL) simulation

• Deployment with Simulink Compiler™

• Production code generation using Simulink Coder™ or Embedded Coder^®

Version History

Introduced in R2026b