lpvss

Linear parameter-varying state-space model

Since R2023a

Description

Use lpvss to represent linear state-space models whose dynamics vary as a function of time-dependent parameters. Linear parameter-varying (LPV) models are helpful to obtain low-complexity, locally linear approximations of nonlinear systems. They can model a much richer class of behaviors than LTI models, especially when the parameters are allowed to depend on internal states (quasi-LPV). Hence, using lpvss models lets you efficiently apply design techniques, such as gain-scheduled control, to nonlinear models.

You can use lpvss to create continuous-time or discrete-time linear parameter-varying state-space models. In continuous time, an lpvss model is described by the following state-space equations.

$$\begin{array}{c}E(t,p)\dot{x}={\delta }_0(t,p)+A(t,p)(x-x_0(t,p))+B(t,p)(u-u_0(t,p))\\ y(t)=y_0(t,p)+C(t,p)(x-x_0(t,p))+D(t,p)(u-u_0(t,p))\end{array}$$

Here, p is a vector of time-dependent exogenous parameters and δ₀(t,p), x₀(t,p), u₀(t,p), and y₀(t,p) are varying derivative, state, input, and output offsets, respectively.

In discrete time, an lpvss model is described by the following state-space equations.

$$\begin{array}{c}E(k,p_k)x_{k+1}={\delta }_0(k,p_k)+A(k,p_k)(x_k-x_0(k,p_k))+B(k,p_k)(u_k-u_0(k,p_k))\\ y_k=y_0(k,p_k)+C(k,p_k)(x_k-x_0(k,p_k))+D(k,p_k)(u_k-u_0(k,p_k))\end{array}$$

Here, the integer index k counts the number of sampling periods Ts.

You can use an lpvss object to model:

• Linear systems whose coefficients depend on external or environmental parameters. For an example, see Control Design for Spinning Disks.

• Nonlinear systems operating near steady-state conditions that change in time and depend on a few physical parameters. For example, see Design and Validate Gain-Scheduled Controller for Nonlinear Aircraft Pitch Dynamics.

Use lpvss to construct LPV models whose dynamics are described by a MATLAB^® function (the data function). Use ssInterpolant to construct LPV models that interpolate linearized LTI dynamics over a grid of operating conditions. The lpvss object cannot represent quasi-LPV models consisting of an LPV model with a scheduling map p(t) = h(t,x,u), but you can specify the parameter trajectory as a function of time t, states x, and inputs u to simulate quasi-LPV models. See LPV and LTV Models for functions and operations applicable to lpvss objects.

Creation

Syntax

lpvSys = lpvss(ParamNames,DataFcn)

lpvSys = lpvss(ParamNames,DataFcn,ts)

lpvSys = lpvss(ParamNames,DataFcn,ts,tcheck,pcheck)

lpvSys = lpvss(___,Name=Value)

Description

lpvSys = lpvss(ParamNames,DataFcn) creates a continuous-time LPV model. ParamNames specifies a name for each element of the parameter vector p. DataFcn is the name or a handle to the data function, the user-defined MATLAB function that calculates the matrices and offsets for given (t,p) values (or (k,p) values in discrete time).

lpvSys = lpvss(ParamNames,DataFcn,ts) creates a discrete-time LPV model with sample time ts.

lpvSys = lpvss(ParamNames,DataFcn,ts,tcheck,pcheck) evaluates DataFcn at (tcheck,pcheck) to determine the number of states, inputs, and outputs. By default, lpvss uses (tcheck,pcheck) = (0,0).

lpvSys = lpvss(___,Name=Value) sets properties of the linear parameter-varying model using one or more name-value arguments. Use this syntax with any of the previous input-argument combinations.

Input Arguments

ParamNames — Parameter names

cell array of character vectors

Parameter names, specified as an N_p-by-1 cell array of character vectors, where N_p is the number of scalar parameters, that is, the number of elements in the parameter vector p. This input sets the value of the property ParameterName.

DataFcn — Data function

function name | function handle

User-defined MATLAB function for calculating matrices and offsets, specified as a function name (character vector or string) or a function handle. The data function must be of the following form.

• Continuous time — $$[A,B,C,D,E,{\delta }_0,x_0,u_0,y_0,Delays]=f(t,p)$$

• Discrete time — $$[A,B,C,D,E,{\delta }_0,x_0,u_0,y_0,Delays]=f(k,p)$$

The Delay argument is a structure with fields Input and Output specifying the delays in input and output channels, respectively. (since R2024a)

For more information about defining a data function, see Data Function.

This input sets the value of property DataFunction.

ts — Sample time

scalar

Sample time, specified as a scalar. For more information, see the Ts property.

tcheck — Time test value

scalar

Test value for time, specified as a scalar. The object evaluates DataFcn at (tcheck,pcheck) to determine the number of states, inputs, and outputs. By default, lpvss uses (tcheck,pcheck) = (0,0).

pcheck — Parameter test value

scalar | vector

Test value for parameters, specified as a scalar or vector of length N_p. The object evaluates DataFcn at (tcheck,pcheck) to determine the number of states, inputs, and outputs. By default, lpvss uses (tcheck,pcheck) = (0,0).

Properties

ParameterName — Parameter names

'' (default) | cell array of character vectors

Names of the parameters in the LPV model, specified as a cell array of character vectors. Specify a cell array of length equal to the length of parameter vector p.

DataFunction — Data function

[] (default) | function handle

Data function for calculating the model data, specified as a function handle. The data function must be of the following form.

• Continuous time

  [A,B,C,D,E,dx0,x0,u0,y0,Delay] = DataFcn(t,p)

• Discrete time

  [A,B,C,D,E,dx0,x0,u0,y0,Delay] = DataFcn(k,p)

  Here, the input k is an integer index that counts the number of sampling periods Ts. The absolute time is given by t = k*Ts.

To pass additional input arguments, use an anonymous function as follows.

DataFcn = @(t) myFunction(t,arg1,arg2,...)

You can set all output arguments except A, B, C, D to [] when absent for (t,p) values.

StateName — State names

' ' (default) | character vector | cell array of character vectors

State names, specified as one of the following:

• Character vector — For first-order models, for example, 'velocity'.

• Cell array of character vectors — For models with two or more states.

StateName is empty ' ' for all states by default.

StatePath — State path

' ' (default) | character vector | cell array of character vectors

State path to facilitate state block path management in linearization, specified as one of the following:

• Character vector — For first-order models

• Cell array of character vectors — For models with two or more states

StatePath is empty ' ' for all states by default.

StateUnit — State units

' ' (default) | character vector | cell array of character vectors

State units, specified as one of the following:

• Character vector — For first-order models, for example, 'm/s'

• Cell array of character vectors — For models with two or more states

Use StateUnit to keep track of the units of each state. StateUnit has no effect on system behavior. StateUnit is empty ' ' for all states by default.

Ts — Sample time

0 (default) | positive scalar | -1

Sample time, specified as:

• 0 for continuous-time systems.

• A positive scalar representing the sampling period of a discrete-time system. Specify Ts in the time unit specified by the TimeUnit property.

• -1 for a discrete-time system with an unspecified sample time.

Note

Changing Ts does not discretize or resample the model. To convert between continuous-time and discrete-time representations, use c2d and d2c. To change the sample time of a discrete-time system, use d2d.

TimeUnit — Time variable units

'seconds' (default) | 'nanoseconds' | 'microseconds' | 'milliseconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years' | ...

Time variable units, specified as one of the following:

• 'nanoseconds'

• 'microseconds'

• 'milliseconds'

• 'seconds'

• 'minutes'

• 'hours'

• 'days'

• 'weeks'

• 'months'

• 'years'

Changing TimeUnit has no effect on other properties, but changes the overall system behavior. Use chgTimeUnit to convert between time units without modifying system behavior.

InputName — Input channel names

'' (default) | character vector | cell array of character vectors

Input channel names, specified as one of the following:

• A character vector, for single-input models.

• A cell array of character vectors, for multi-input models.

• '', no names specified, for any input channels.

Alternatively, you can assign input names for multi-input models using automatic vector expansion. For example, if sys is a two-input model, enter the following.

sys.InputName = 'controls';

The input names automatically expand to {'controls(1)';'controls(2)'}.

You can use the shorthand notation u to refer to the InputName property. For example, sys.u is equivalent to sys.InputName.

Use InputName to:

• Identify channels on model display and plots.

• Extract subsystems of MIMO systems.

• Specify connection points when interconnecting models.

InputUnit — Input channel units

'' (default) | character vector | cell array of character vectors

Input channel units, specified as one of the following:

• A character vector, for single-input models.

• A cell array of character vectors, for multi-input models.

• '', no units specified, for any input channels.

Use InputUnit to specify input signal units. InputUnit has no effect on system behavior.

InputGroup — Input channel groups

structure

Input channel groups, specified as a structure. Use InputGroup to assign the input channels of MIMO systems into groups and refer to each group by name. The field names of InputGroup are the group names and the field values are the input channels of each group. For example, enter the following to create input groups named controls and noise that include input channels 1 and 2, and 3 and 5, respectively.

sys.InputGroup.controls = [1 2];
sys.InputGroup.noise = [3 5];

You can then extract the subsystem from the controls inputs to all outputs using the following.

sys(:,'controls')

By default, InputGroup is a structure with no fields.

OutputName — Output channel names

'' (default) | character vector | cell array of character vectors

Output channel names, specified as one of the following:

• A character vector, for single-output models.

• A cell array of character vectors, for multi-output models.

• '', no names specified, for any output channels.

Alternatively, you can assign output names for multi-output models using automatic vector expansion. For example, if sys is a two-output model, enter the following.

sys.OutputName = 'measurements';

The output names automatically expand to {'measurements(1)';'measurements(2)'}.

You can also use the shorthand notation y to refer to the OutputName property. For example, sys.y is equivalent to sys.OutputName.

Use OutputName to:

• Identify channels on model display and plots.

• Extract subsystems of MIMO systems.

• Specify connection points when interconnecting models.

OutputUnit — Output channel units

'' (default) | character vector | cell array of character vectors

Output channel units, specified as one of the following:

• A character vector, for single-output models.

• A cell array of character vectors, for multi-output models.

• '', no units specified, for any output channels.

Use OutputUnit to specify output signal units. OutputUnit has no effect on system behavior.

OutputGroup — Output channel groups

structure

Output channel groups, specified as a structure. Use OutputGroup to assign the output channels of MIMO systems into groups and refer to each group by name. The field names of OutputGroup are the group names and the field values are the output channels of each group. For example, create output groups named temperature and measurement that include output channels 1, and 3 and 5, respectively.

sys.OutputGroup.temperature = [1];
sys.OutputGroup.measurement = [3 5];

You can then extract the subsystem from all inputs to the measurement outputs using the following.

sys('measurement',:)

By default, OutputGroup is a structure with no fields.

Name — System name

'' (default) | character vector

System name, specified as a character vector. For example, 'system_1'.

Notes — User-specified text

{} (default) | character vector | cell array of character vectors

User-specified text that you want to associate with the system, specified as a character vector or cell array of character vectors. For example, 'System is MIMO'.

UserData — User-specified data

[] (default) | any MATLAB data type

User-specified data that you want to associate with the system, specified as any MATLAB data type.

Object Functions

Sampling and Interpolation

sample	(Not recommended) Sample linear parameter-varying or time-varying dynamics
ssInterpolant	Build gridded LTV or LPV model from state-space data

Time Response Simulation

step	Step response of dynamic system
impulse	Impulse response plot of dynamic system; impulse response data
lsim	Compute time response simulation data of dynamic system to arbitrary inputs
initial	System response to initial states of state-space model

Model Interconnection

feedback	Feedback connection of multiple models
connect	Block diagram interconnections of dynamic systems
series	Series connection of two models
parallel	Parallel connection of two models
lft	Generalized feedback interconnection of two models (Redheffer star product)

Model Transformation

c2d	Convert model from continuous to discrete time
d2c	Convert model from discrete to continuous time
d2d	Resample discrete-time model
xperm	Reorder states in state-space models
sminreal	Eliminates structurally disconnected states, delays, and blocks

Examples

Continuous-Time Linear Parameter-Varying Model

Create a continuous-time SISO linear-parameter varying model.

For this example, dataFcnMaglev.m defines the matrices and offsets of a magnetic levitation system. The magnetic levitation controls the height of a levitating ball using a coil current that creates a magnetic force on the ball.

These matrices and offsets are defined in the dataFcnMaglev.m data function provided with this example.

Create an LPV model.

lpvsys = lpvss('p',@dataFcnMaglev)

Continuous-time state-space LPV model with 1 outputs, 1 inputs, 2 states, and 1 parameters.
Model Properties

View the data function.

type dataFcnMaglev.m

function [A,B,C,D,E,dx0,x0,u0,y0,Delays] = dataFcnMaglev(~,p)
% MAGLEV example:
% x = [h ; dh/dt]
% p=hbar (equilibrium height)
mb = 0.02; % kg
g = 9.81;
alpha = 2.4832e-5;
A = [0 1;2*g/p 0];
B = [0 ; -2*sqrt(g*alpha/mb)/p];
C = [1 0];  % h
D = 0;
E = [];
dx0 = [];
x0 = [p;0];
u0 = sqrt(mb*g/alpha)*p;  % ibar
y0 = p;                   % y = h = hbar + (h-hbar)
Delays = [];

Discrete-Time Linear Parameter-Varying Model

Create a discrete-time linear-parameter varying model.

The matrices and offsets are given by:

$\mathit{A}=\sin \left(0.1\mathit{p}\right)$, $\mathit{B}=1$, $\mathit{C}=1$, $\mathit{D}=0$

$${\mathit{y}}_0=0.1\sin \left(\mathit{k}\right)$$.

These matrices and offsets are defined in the lpvFcnDiscrete.m data function provided with this example.

Specify the properties and create the LPV model.

Ts = 0.01;
ParamNames = 'p';
DataFcn = @lpvFcnDiscrete;
lpvSys = lpvss(ParamNames,DataFcn,Ts)

Discrete-time state-space LPV model with 1 outputs, 1 inputs, 1 states, and 1 parameters.

View the data function.

type lpvFcnDiscrete.m

function [A,B,C,D,E,dx0,x0,u0,y0,Delays] = lpvFcnDiscrete(k,p)
A = sin(0.1*p);
B = 1;
C = 1;
D = 0;
E = [];
dx0 = [];
x0 = [];
u0 = [];
y0 = 0.1*sin(k);
Delays = [];

Time Response of Linear-Parameter Varying State-Space Model

For this example, dataFcnMaglev.m defines the matrices and offsets of a magnetic levitation system. The magnetic levitation controls the height of a levitating ball using a coil current that creates a magnetic force on the ball. This example simulates the model in open loop.

Create an LPV model.

lpvSys = lpvss('h',@dataFcnMaglev)

Continuous-time state-space LPV model with 1 outputs, 1 inputs, 2 states, and 1 parameters.
Model Properties

You can set additional properties using the dot notation.

lpvSys.StateName = {'h','hdot'};
lpvSys.InputName = 'current';
lpvSys.InputName = 'height';

Simulate the response of this model to an arbitrary sinusoidal input current.

h0 = 1;
[~,~,~,~,~,~,x0,u0,~] = dataFcnMaglev([],h0);
t = 0:1e-3:1;
u = u0*(1+0.1*sin(10*t));
y = lsim(lpvSys,u,t,x0,@(t,x,u) x(1));

Plot the response.

plot(t,y,t,u/u0)
legend('height','current')

The ball is attracted to the magnet when the current first increases (h decreases). The subsequent decrease in current is not enough to bring it back.

h = 0 is a singularity for this model, that is, the ball hits the magnet. The LPV model ceases to be valid at this point.

Sample Dynamics of LPV Models

You can sample the dynamics of an LPV model over a point or a grid of ($\mathit{t}$,$\mathit{p}$) values to obtain affine dynamics for a given time or parameter value.

For this example, dataFcnMaglev.m defines the matrices and offsets of a magnetic levitation system. The magnetic levitation controls the height of a levitating ball using a coil current that creates a magnetic force on the ball.

Create an LPV model.

lpvSys = lpvss('h',@dataFcnMaglev)

Continuous-time state-space LPV model with 1 outputs, 1 inputs, 2 states, and 1 parameters.

Sample the LPV dynamics at three h values to obtain local LTI models.

hmin = 0.05;
hmax = 0.25;
hcd = linspace(hmin,hmax,3);
ssArray = psample(lpvSys,[],hcd);
size(ssArray)

1x3 array of state-space models.
Each model has 1 outputs, 1 inputs, and 2 states.

The function stores the model offsets in the Offsets property of the array.

ssArray.Offsets

ans=1×3 struct array with fields:
    dx
    x
    u
    y

Plot the Bode response.

bodemag(ssArray)

View the data function.

type dataFcnMaglev.m

function [A,B,C,D,E,dx0,x0,u0,y0,Delays] = dataFcnMaglev(~,p)
% MAGLEV example:
% x = [h ; dh/dt]
% p=hbar (equilibrium height)
mb = 0.02; % kg
g = 9.81;
alpha = 2.4832e-5;
A = [0 1;2*g/p 0];
B = [0 ; -2*sqrt(g*alpha/mb)/p];
C = [1 0];  % h
D = 0;
E = [];
dx0 = [];
x0 = [p;0];
u0 = sqrt(mb*g/alpha)*p;  % ibar
y0 = p;                   % y = h = hbar + (h-hbar)
Delays = [];

Create LPV Models with Delays

Since R2024a

This example shows how to create a linear parameter-varying model containing a varying delay. In this example, you also simulate a closed-loop plant with a controller containing an output delay and observe the effects of delayed controller response.

For this example, dataFcnMaglev.m defines the matrices and offsets of a magnetic levitation system. The magnetic levitation controls the height of a levitating ball using a coil current that creates a magnetic force on the ball.

Create an LPV model.

h0 = 1;  % Note: Singular for h=0
G = lpvss("h",@dataFcnMaglev,0,0,h0);

This example also provides a data function maglevPD.m which defines a gain-scheduled PD controller for the magnetic levitation plant, containing a time-dependent output delay. This delay decreases with time.

PD = lpvss("h",@maglevPD,0,0,h0);

Create the closed-loop response.

CL = feedback(G*PD,1);

Simulate the response to the true trajectory $\mathit{p}\left(\mathit{t}\right)=\mathit{h}\left(\mathit{t}\right)$, which is the first state.

xinit = [h0;0;0];  % init: h=1
t = 0:1e-2:10;
href = h0+0.5*sin(t);  % desired height
pFcn = @(t,x,u) x(1);
[y1,~,x1,p1] = lsim(CL,href,t,xinit,pFcn);

Plot the simulation results and compare to reference height.

plot(t,href,t,y1,'r--')
legend("Height reference","LPV simulation")

Because of the delay in controller action, the output signal also has a delayed response of tracking the reference input accurately. As the delay reduces over time, the LPV simulation matches the reference.

Data Functions

type dataFcnMaglev.m

function [A,B,C,D,E,dx0,x0,u0,y0,Delays] = dataFcnMaglev(~,p)
% MAGLEV example:
% x = [h ; dh/dt]
% p=hbar (equilibrium height)
mb = 0.02; % kg
g = 9.81;
alpha = 2.4832e-5;
A = [0 1;2*g/p 0];
B = [0 ; -2*sqrt(g*alpha/mb)/p];
C = [1 0];  % h
D = 0;
E = [];
dx0 = [];
x0 = [p;0];
u0 = sqrt(mb*g/alpha)*p;  % ibar
y0 = p;                   % y = h = hbar + (h-hbar)
Delays = [];

type maglevPD.m

function [A,B,C,D,E,dx0,x0,u0,y0,Delays] = maglevPD(t,p)
% Gain-scheduled PD for MAGLEV example:
%    dz = A(p) z + B(p) e
%     u = u0 + C(p) z + D(p) e
% p=h (equilibrium height)
mb = 0.02; % kg
g = 9.81;
alpha = 2.4832e-5;
a0 = 2*g/p;
b0 = -2*sqrt(g*alpha/mb)/p;
wn = 10;
zeta = 0.7;
Kp = (a0+wn^2)/b0;
Kd = 2*zeta*wn/b0;  % linear in p
% Kp = (2*zeta*wn-a0)/b0;
% Kd = wn^2/b0;
wf = 100;
A = -wf;
B = wf;
C = -wf*Kd;
D = Kp+wf*Kd;
E = [];
dx0 = [];
x0 = [];
u0 = [];
y0 = sqrt(mb*g/alpha)*p;     % ibar, feedforward term
Delays.Output = 0.1/(1+t);  % decreasing delay
Delays.Input = NaN;
end

Version History

Introduced in R2023a

R2024a: Data Function: Support for specifying input and output delays

Use the Delay argument of the data function to specify fixed or varying delays. The Delay argument is a structure with fields Input and Output specifying the delays in input and output channels, respectively. Set Delay.Input and Delay.Output to vectors with length equal to the number of input and output channels, respectively. To indicate the absence of delay in a particular channel at all times, set the corresponding value in the vector to NaN. For example, for a three-input system, Delay.Input = [0.1 NaN sin(0.2*p)] defines a fixed delay in the first input channel, no delay in the second channel, and a varying delay in the third input channel. For more information about the data function, see Data Function