# 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\left(t,p\right)\stackrel{˙}{x}={\delta }_{0}\left(t,p\right)+A\left(t,p\right)\left(x-{x}_{0}\left(t,p\right)\right)+B\left(t,p\right)\left(u-{u}_{0}\left(t,p\right)\right)\\ y\left(t\right)={y}_{0}\left(t,p\right)+C\left(t,p\right)\left(x-{x}_{0}\left(t,p\right)\right)+D\left(t,p\right)\left(u-{u}_{0}\left(t,p\right)\right)\end{array}$`

Here, p is a vector of time-dependent exogenous parameters and δ0(t), x0(t), u0(t), and y0(t) are time-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\left(k,{p}_{k}\right){x}_{k+1}={\delta }_{0}\left(k,{p}_{k}\right)+A\left(k,{p}_{k}\right)\left({x}_{k}-{x}_{0}\left(k,{p}_{k}\right)\right)+B\left(k,{p}_{k}\right)\left({u}_{k}-{u}_{0}\left(k,{p}_{k}\right)\right)\\ {y}_{k}={y}_{0}\left(k,{p}_{k}\right)+C\left(k,{p}_{k}\right)\left({x}_{k}-{x}_{0}\left(k,{p}_{k}\right)\right)+D\left(k,{p}_{k}\right)\left({u}_{k}-{u}_{0}\left(k,{p}_{k}\right)\right)\end{array}$`

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

You can use an `lpvss` object to model:

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 implicitly 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

example

````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).```

example

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

example

````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).```

example

````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

expand all

Parameter names, specified as an Np-by-1 cell array of character vectors, where Np 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`.

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 — $\left[A,B,C,D,E,{\delta }_{0},{x}_{0},{u}_{0},{y}_{0},Delays\right]=f\left(t,p\right)$

• Discrete time — $\left[A,B,C,D,E,{\delta }_{0},{x}_{0},{u}_{0},{y}_{0},Delays\right]=f\left(k,p\right)$

Set Delays to `[]`. In future releases, this argument will allow you to specify model delays.

This input sets the value of property `DataFunction`.

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

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).

Test value for parameters, specified as a scalar or vector of length Np. 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

expand all

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.

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.

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.

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.

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.

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`.

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.

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.

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.

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.

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.

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.

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 = ; 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.

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

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'`.

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

## Object Functions

expand all

 `sample` Sample linear parameter-varying or time-varying dynamics `ssInterpolant` Build gridded LTV or LPV model from state-space data
 `step` Step response of dynamic system `impulse` Impulse response plot of dynamic system; impulse response data `lsim` Plot simulated time response of dynamic system to arbitrary inputs; simulated response data `initial` System response to initial states of state-space model
 `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)
 `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` Structural pole/zero cancellations

## Examples

collapse all

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 = []; ```

Create a discrete-time linear-parameter varying model.

The matrices and offsets are given by:

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

${\mathit{y}}_{0}=0.1\mathrm{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 = []; ```

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.

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 `h` = 1 to obtain local LTI models.

```hmin = 0.05; hmax = 0.25; hcd = linspace(hmin,hmax,3); [ssArray,offsets] = sample(lpvSys,[],hcd); size(ssArray)```
```1x3 array of state-space models. Each model has 1 outputs, 1 inputs, and 2 states. ```

Plot the Bode response.

`bodemag(ssArray)` ## Version History

Introduced in R2023a